cmTaskMgr.h : Initial working version.

cmTaskMgr.h

@@ -12,6 +12,7 @@ extern "C" {
     kInvalidArgTmRC,
     kOpFailTmRC,
     kQueueFailTmRC,
+    kAssertFailTmRC,
     kTestFailTmRC
   };
 
@@ -25,8 +26,8 @@ extern "C" {
   {
     kInvalidTmId,
     kQueuedTmId,       // The task is waiting in the queue.
-    kQueuedPausedTmId, // The task is waiting in the queue but is deferred.
     kStartedTmId,      // The task is running.
+    kPausedTmId,       // The task is paused.
     kCompletedTmId,    // The task successfully completed.
     kKilledTmId        // The task was killed by the client.
   } cmStatusTmId_t;
@@ -40,6 +41,7 @@ extern "C" {
 
   typedef enum 
   { 
+    kNoneTmId,
     kStartTmId, 
     kPauseTmId, 
     kKillTmId 
@@ -62,13 +64,13 @@ extern "C" {
 
   typedef struct cmTaskMgrFuncArg_str
   {
+    void*               reserved; 
     void*               arg;           // 'funcArg' provided by cmTaskMgrCall();
     unsigned            argByteCnt;    // 'funcArgByteCnt' provided by cmTaskMgrCall()
     unsigned            instId;        // Task instance id.
     cmTaskMgrStatusCb_t statusCb;      // Status update function provided by cmTaskMgrCreate().
     void*               statusCbArg;   // Status update function arg. provided by cmTaskMgrCreate().
     unsigned            progCnt;       // Maximum expected value of cmTaskMgrStatusArg_t.prog during execution of this task instance.
-    cmTaskMgrCtlId_t*   cmdIdPtr;      // Command id used to inform the running task that it should pause or exit.
     unsigned            pauseSleepMs;  // Length of time to sleep if the task receives a pause command.
   } cmTaskMgrFuncArg_t;
 
@@ -83,8 +85,12 @@ extern "C" {
     unsigned             queueByteCnt,
     unsigned             pauseSleepMs );
 
+  // Calling cmTaskMgrDestroy() will send a 'kill' control message
+  // to any existing worker threads.  The threads will shutdown
+  // gracefully but the task they were computing will not be completed.
   cmTmRC_t cmTaskMgrDestroy( cmTaskMgrH_t* hp );
 
+  // Return true if the task manager handle is valid.
   bool     cmTaskMgrIsValid(   cmTaskMgrH_t h );
 
   // Called by the client to give the task mgr an opportunity to execute
@@ -95,13 +101,19 @@ extern "C" {
   cmTmRC_t cmTaskMgrOnIdle( cmTaskMgrH_t h );
 
   // Pause/unpause the task mgr.
+  // This function pauses/unpauses each worker thread and then the master thread.
+  // If waitFl is set then the function will not return until each of
+  // the threads has entered the requested state. If 'waitFl' is false
+  // The function will wait for the worker threads to pause but will
+  // only signal the master thread to pause before returning.
   bool     cmTaskMgrIsEnabled( cmTaskMgrH_t h );
   cmTmRC_t cmTaskMgrEnable(    cmTaskMgrH_t h, bool enableFl );
 
   // Install a task function and associate it with a label and unique id.
   cmTmRC_t cmTaskMgrInstall( cmTaskMgrH_t h, unsigned taskId, const cmChar_t* label, cmTaskMgrFunc_t func ); 
 
-  // Queue a task.
+  // Queue a new task instance.
+  // The 'queued' status callback occurs from inside this call.
   cmTmRC_t cmTaskMgrCall( 
     cmTaskMgrH_t h, 
     unsigned     taskId, 
@@ -109,18 +121,25 @@ extern "C" {
     unsigned     progCnt, 
     unsigned*    retInstIdPtr ); 
 
-  // Start,pause, or kill a task.  
-  // If a queued task is paused then it will remain at the front of the queue
-  // and tasks behdind it in the queue will be executed.
+  // Start,pause, or kill a task instance.  
+  // If a queued task is paused then it will remain at the front
+  // of the queue and tasks behdind it in the queue will be executed.
   cmTmRC_t cmTaskMgrTaskCtl( cmTaskMgrH_t h, unsigned instId, cmTaskMgrCtlId_t ctlId );
 
   // Get the status of a task.
   cmStatusTmId_t cmTaskMgrStatus( cmTaskMgrH_t h, unsigned instId );
 
-  
-  const void* cmTaskMgrResult( cmTaskMgrH_t h, unsigned instId );
+  // 
+  const void* cmTaskMgrResult(          cmTaskMgrH_t h, unsigned instId );
   unsigned    cmTaskMgrResultByteCount( cmTaskMgrH_t h, unsigned instId );
-  cmTmRC_t    cmTaskMgrResultDelete(    cmTaskMgrH_t h, unsigned instId );
+  cmTmRC_t    cmTaskMgrInstDelete(      cmTaskMgrH_t h, unsigned instId );
+
+
+  // -----------------------------------------------------------------------------------
+  // Worker thread helper functions.
+  cmTaskMgrCtlId_t cmTaskMgrHandleCommand( cmTaskMgrFuncArg_t* a );
+  cmTaskMgrCtlId_t cmTaskMgrSendStatus( cmTaskMgrFuncArg_t* a, cmStatusTmId_t statusId );
+  cmTaskMgrCtlId_t cmTaskMgrSendProgress( cmTaskMgrFuncArg_t* a, unsigned prog );
 
   cmTmRC_t cmTaskMgrTest(cmCtx_t* ctx);