Commits

badi committed 2600358

proof-read documentation

Comments (0)

Files changed (1)

 mktask :: Show a => a -> IO Task
 mktask v = do
 
-  -- the script to execute: intercalate with '\n' then convert to ByteString
+  -- the bash script to execute: sleep a max of 10 seconds then echo the parameter
   let script = BS.pack . unlines $ [
               "t=$(echo $RANDOM % 10 | bc)"
             , "sleep $t"
             ]
 
   -- Create the Task.
-  -- 'task' :: Command -> IO Task
-  -- 'cmd'  :: String -> Command
+  -- cmd  :: String -> Command
+  -- task :: Command -> IO Task
   t <- task $ cmd "bash script.sh"
 
   -- specifyBuffer :: Task -> ByteString -> Location Remote -> Cached -> IO ()
-  -- 'remote' :: FilePath -> Location Remote
-  -- Locations can be either 'Location Local' or 'Location Remote', which have different semantic meanings.
+  -- remote :: FilePath -> Location Remote
+  -- Locations can be either 'Location Local' or 'Location Remote', which have different semantic meanings:
+  -- both are 'FilePath's, but the former is on the Master and the latter the Worker.
   -- If we used for instance 'specifyFile', it has type Task -> Location Local -> Location Remote -> Cached -> IO ()
-  -- This prevents local & remote files from being nigligently swapped. There are appropriate 'smart constructor's for each:
-  -- 'remote' and 'local' to create them as needed.
+  -- This prevents local & remote files from being nigligently swapped. There are appropriate "smart constructor"s for each:
+  -- use 'remote' and 'local' to create them as needed.
   specifyBuffer t script (remote "script.sh") False
 
   -- Set the tag for the task.
 
   return t
 
--- | Intended to run as part of the event loop prior to calling 'work_queue_wait'
---   Used as a callback, it accepts the current WorkQueue and can perform arbitrary actions
+
+-- | Callback for the start of the event loop, called prior to 'work_queue_wait'
+--   It accepts the current WorkQueue and can perform arbitrary actions.
 --   In this case though, all it does is get the current runtime
 --   WorkQueue statistics and print the number of tasks running,
 --   waiting, and complete to stdout
   -- ...but prettier
   print $ map ($ s) [tasksRunning, tasksWaiting, tasksComplete]
 
+
 -- | Callback for when a Task is successfully returned.
 --   Executed after calling 'work_queue_wait'
 --  In this instance, just print the task tag and the task output to stdout
---  We then need to call delete b/c Tasks aren't tracked by the garbage collector
+--  We then need to call delete b/c Tasks aren't tracked by the garbage collector.
 processResult :: WorkQueue -> Task -> IO ()
 processResult q r = do
   putStrLn $ "Got: " ++ show (tag r)
   BS.putStrLn . output $ r
   delete r
 
+
+
 main = do
 
   -- Make WorkQueue print out all debugging information.  This is
   -- Create the WorkQueue. We override the default parameters to
   -- change the port to 1024, use a catalog server, set the project
   -- name to "hswq", and log the runtime stats to "/tmp/wq.log"
+  -- The default parameters only specify port 9123 and the catalog server, project name, and logging are disabled.
   -- workqueue :: QueueParams -> IO WorkQueue
   q  <- workqueue $ defaultQParams { _qport   = Just $ port 1024
                                    , _mode    = Just Catalog
 
   -- The eventLoop provides a while loop that waits until all tasks in the queue are complete.
   -- Two callbacks can be provided:
-  --   the first is called at the start of the loop with the WorkQueue as the parameter.
-  --   the second is called only on successfully returned Tasks
+  --   - the first is called at the start of the loop with the WorkQueue as the parameter.
+  --   - the second is called only on successfully returned Tasks
   --
   -- The type is:
   -- eventLoop :: WorkQueue -> Timeout -> (WorkQueue -> IO ()) -> (WorkQueue -> Task -> IO ()) -> IO ()
   --      when r is Just: process q r
   --
   -- In this case, we set the Timeout to 1 second (Timeouts are either
-  -- 'Forever' or a positive number of seconds (specified at the
-  -- type-level)).
-  -- The 'update' callback prints the current runtime statistics,
-  -- while the 'process' callback prints the task tag and output to
-  -- stdout
+  -- 'Forever' or a positive number of seconds. The 'printStats' callback
+  -- prints the current runtime statistics, while the 'processResult'
+  -- callback prints the task tag and output to stdout
   eventLoop q (seconds 1) printStats processResult
 
   putStrLn "Done!"