libcm is a C development framework with an emphasis on audio signal processing applications.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150
  1. #ifndef cmTaskMgr_h
  2. #define cmTaskMgr_h
  3. #ifdef __cplusplus
  4. extern "C" {
  5. #endif
  6. enum
  7. {
  8. kOkTmRC,
  9. kThreadFailTmRC,
  10. kInvalidArgTmRC,
  11. kOpFailTmRC,
  12. kQueueFailTmRC,
  13. kAssertFailTmRC,
  14. kTestFailTmRC
  15. };
  16. typedef cmRC_t cmTmRC_t;
  17. typedef cmHandle_t cmTaskMgrH_t;
  18. extern cmTaskMgrH_t cmTaskMgrNullHangle;
  19. typedef enum
  20. {
  21. kInvalidTmId,
  22. kQueuedTmId, // The task is waiting in the queue.
  23. kStartedTmId, // The task is running.
  24. kPausedTmId, // The task is paused.
  25. kCompletedTmId, // The task successfully completed.
  26. kKilledTmId // The task was killed by the client.
  27. } cmStatusTmId_t;
  28. typedef enum
  29. {
  30. kStatusTmId, // Task status updates. These are automatically sent by the system when the task instance changes state.
  31. kProgTmId, // Task progress update. The user function should increment the 'prog' toward 'progCnt'.
  32. kErrorTmId // Error message
  33. } cmSelTmId_t;
  34. typedef enum
  35. {
  36. kNoneTmId,
  37. kStartTmId,
  38. kPauseTmId,
  39. kKillTmId
  40. } cmTaskMgrCtlId_t;
  41. typedef struct cmTaskMgrStatusArg_str
  42. {
  43. void* arg;
  44. unsigned instId;
  45. cmSelTmId_t selId;
  46. cmStatusTmId_t statusId;
  47. unsigned prog;
  48. const cmChar_t* msg;
  49. void* result;
  50. unsigned resultByteCnt;
  51. } cmTaskMgrStatusArg_t;
  52. typedef void (*cmTaskMgrStatusCb_t)( const cmTaskMgrStatusArg_t* status );
  53. typedef struct cmTaskMgrFuncArg_str
  54. {
  55. void* reserved;
  56. void* arg; // 'funcArg' provided by cmTaskMgrCall();
  57. unsigned argByteCnt; // 'funcArgByteCnt' provided by cmTaskMgrCall()
  58. unsigned instId; // Task instance id.
  59. cmTaskMgrStatusCb_t statusCb; // Status update function provided by cmTaskMgrCreate().
  60. void* statusCbArg; // Status update function arg. provided by cmTaskMgrCreate().
  61. unsigned progCnt; // Maximum expected value of cmTaskMgrStatusArg_t.prog during execution of this task instance.
  62. unsigned pauseSleepMs; // Length of time to sleep if the task receives a pause command.
  63. } cmTaskMgrFuncArg_t;
  64. typedef void (*cmTaskMgrFunc_t)(cmTaskMgrFuncArg_t* arg );
  65. cmTmRC_t cmTaskMgrCreate(
  66. cmCtx_t* ctx,
  67. cmTaskMgrH_t* hp,
  68. cmTaskMgrStatusCb_t statusCb,
  69. void* statusCbArg,
  70. unsigned maxActiveThreadCnt,
  71. unsigned queueByteCnt,
  72. unsigned pauseSleepMs );
  73. // Calling cmTaskMgrDestroy() will send a 'kill' control message
  74. // to any existing worker threads. The threads will shutdown
  75. // gracefully but the task they were computing will not be completed.
  76. cmTmRC_t cmTaskMgrDestroy( cmTaskMgrH_t* hp );
  77. // Return true if the task manager handle is valid.
  78. bool cmTaskMgrIsValid( cmTaskMgrH_t h );
  79. // Called by the client to give the task mgr an opportunity to execute
  80. // period functions from within the client thread. Note that 'statusCb()'
  81. // (as passed to cmTaskMgrCreate()) is only called within this function
  82. // This guarantees that all communication with the client occurs in the
  83. // clients thread.
  84. cmTmRC_t cmTaskMgrOnIdle( cmTaskMgrH_t h );
  85. // Pause/unpause the task mgr.
  86. // This function pauses/unpauses each worker thread and then the master thread.
  87. // If waitFl is set then the function will not return until each of
  88. // the threads has entered the requested state. If 'waitFl' is false
  89. // The function will wait for the worker threads to pause but will
  90. // only signal the master thread to pause before returning.
  91. bool cmTaskMgrIsEnabled( cmTaskMgrH_t h );
  92. cmTmRC_t cmTaskMgrEnable( cmTaskMgrH_t h, bool enableFl );
  93. // Install a task function and associate it with a label and unique id.
  94. cmTmRC_t cmTaskMgrInstall( cmTaskMgrH_t h, unsigned taskId, const cmChar_t* label, cmTaskMgrFunc_t func );
  95. // Queue a new task instance.
  96. // The 'queued' status callback occurs from inside this call.
  97. cmTmRC_t cmTaskMgrCall(
  98. cmTaskMgrH_t h,
  99. unsigned taskId,
  100. void* funcArg,
  101. unsigned progCnt,
  102. unsigned* retInstIdPtr );
  103. // Start,pause, or kill a task instance.
  104. // If a queued task is paused then it will remain at the front
  105. // of the queue and tasks behdind it in the queue will be executed.
  106. cmTmRC_t cmTaskMgrTaskCtl( cmTaskMgrH_t h, unsigned instId, cmTaskMgrCtlId_t ctlId );
  107. // Get the status of a task.
  108. cmStatusTmId_t cmTaskMgrStatus( cmTaskMgrH_t h, unsigned instId );
  109. //
  110. const void* cmTaskMgrResult( cmTaskMgrH_t h, unsigned instId );
  111. unsigned cmTaskMgrResultByteCount( cmTaskMgrH_t h, unsigned instId );
  112. cmTmRC_t cmTaskMgrInstDelete( cmTaskMgrH_t h, unsigned instId );
  113. // -----------------------------------------------------------------------------------
  114. // Worker thread helper functions.
  115. cmTaskMgrCtlId_t cmTaskMgrWorkerHandleCommand( cmTaskMgrFuncArg_t* a );
  116. cmTaskMgrCtlId_t cmTaskMgrWorkerSendStatus( cmTaskMgrFuncArg_t* a, cmStatusTmId_t statusId );
  117. cmTaskMgrCtlId_t cmTaskMgrWorkerSendProgress( cmTaskMgrFuncArg_t* a, unsigned prog );
  118. cmTmRC_t cmTaskMgrTest(cmCtx_t* ctx);
  119. #ifdef __cplusplus
  120. }
  121. #endif
  122. #endif