git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-Plus-IoT-SDK/c_sdk/standard/common/include/iot_taskpool.h

   1 /*\r
   2  * Amazon FreeRTOS Common V1.0.0\r
   3  * Copyright (C) 2018 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
   4  *\r
   5  * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
   6  * this software and associated documentation files (the "Software"), to deal in\r
   7  * the Software without restriction, including without limitation the rights to\r
   8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
   9  * the Software, and to permit persons to whom the Software is furnished to do so,\r
  10  * subject to the following conditions:\r
  11  *\r
  12  * The above copyright notice and this permission notice shall be included in all\r
  13  * copies or substantial portions of the Software.\r
  14  *\r
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
  16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
  17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
  18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
  19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
  20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
  21  *\r
  22  * http://aws.amazon.com/freertos\r
  23  * http://www.FreeRTOS.org\r
  24  */\r
  25 \r
  26 /**\r
  27  * @file iot_taskpool.h\r
  28  * @brief User-facing functions of the task pool library.\r
  29  */\r
  30 \r
  31 #ifndef IOT_TASKPOOL_H_\r
  32 #define IOT_TASKPOOL_H_\r
  33 \r
  34 /* The config header is always included first. */\r
  35 #include "iot_config.h"\r
  36 \r
  37 /* Standard includes. */\r
  38 #include <stdbool.h>\r
  39 #include <stdint.h>\r
  40 #include <stddef.h>\r
  41 \r
  42 /* Task pool types. */\r
  43 #include "types/iot_taskpool_types.h"\r
  44 \r
  45 /*------------------------- Task Pool library functions --------------------------*/\r
  46 \r
  47 /**\r
  48  * @functionspage{taskpool,task pool library}\r
  49  * - @functionname{taskpool_function_createsystemtaskpool}\r
  50  * - @functionname{taskpool_function_getsystemtaskpool}\r
  51  * - @functionname{taskpool_function_create}\r
  52  * - @functionname{taskpool_function_destroy}\r
  53  * - @functionname{taskpool_function_setmaxthreads}\r
  54  * - @functionname{taskpool_function_createjob}\r
  55  * - @functionname{taskpool_function_createrecyclablejob}\r
  56  * - @functionname{taskpool_function_createrecyclablesystemjob}\r
  57  * - @functionname{taskpool_function_destroyrecyclablejob}\r
  58  * - @functionname{taskpool_function_recyclejob}\r
  59  * - @functionname{taskpool_function_schedule}\r
  60  * - @functionname{taskpool_function_schedulesystemjob}\r
  61  * - @functionname{taskpool_function_scheduledeferred}\r
  62  * - @functionname{taskpool_function_getstatus}\r
  63  * - @functionname{taskpool_function_trycancel}\r
  64  * - @functionname{taskpool_function_getjobstoragefromhandle}\r
  65  * - @functionname{taskpool_function_strerror}\r
  66  */\r
  67 \r
  68 /**\r
  69  * @functionpage{IotTaskPool_CreateSystemTaskPool,taskpool,createsystemtaskpool}\r
  70  * @functionpage{IotTaskPool_GetSystemTaskPool,taskpool,getsystemtaskpool}\r
  71  * @functionpage{IotTaskPool_Create,taskpool,create}\r
  72  * @functionpage{IotTaskPool_Destroy,taskpool,destroy}\r
  73  * @functionpage{IotTaskPool_SetMaxThreads,taskpool,setmaxthreads}\r
  74  * @functionpage{IotTaskPool_CreateJob,taskpool,createjob}\r
  75  * @functionpage{IotTaskPool_CreateRecyclableJob,taskpool,createrecyclablejob}\r
  76  * @functionpage{IotTaskPool_CreateRecyclableSystemJob,taskpool,createrecyclablesystemjob}\r
  77  * @functionpage{IotTaskPool_DestroyRecyclableJob,taskpool,destroyrecyclablejob}\r
  78  * @functionpage{IotTaskPool_RecycleJob,taskpool,recyclejob}\r
  79  * @functionpage{IotTaskPool_Schedule,taskpool,schedule}\r
  80  * @functionpage{IotTaskPool_ScheduleSystemJob,taskpool,schedule}\r
  81  * @functionpage{IotTaskPool_ScheduleDeferred,taskpool,scheduledeferred}\r
  82  * @functionpage{IotTaskPool_GetStatus,taskpool,getstatus}\r
  83  * @functionpage{IotTaskPool_TryCancel,taskpool,trycancel}\r
  84  * @functionpage{IotTaskPool_GetJobStorageFromHandle,taskpool,getjobstoragefromhandle}\r
  85  * @functionpage{IotTaskPool_strerror,taskpool,strerror}\r
  86  */\r
  87 \r
  88 /**\r
  89  * @brief Creates the one single instance of the system task pool.\r
  90  *\r
  91  * This function should be called once by the application to initialize the one single instance of the system task pool.\r
  92  * An application should initialize the system task pool early in the boot sequence, before initializing any other library\r
  93  * and before posting any jobs. Early initialization it typically easy to accomplish by creating the system task pool\r
  94  * before starting the scheduler.\r
  95  *\r
  96  * This function does not allocate memory to hold the task pool data structures and state, but it\r
  97  * may allocate memory to hold the dependent entities and data structures, e.g. the threads of the task\r
  98  * pool. The system task pool handle is recoverable for later use by calling @ref IotTaskPool_GetSystemTaskPool or\r
  99  * the shortcut @ref IOT_SYSTEM_TASKPOOL.\r
 100  *\r
 101  * @param[in] pInfo A pointer to the task pool initialization data.\r
 102  *\r
 103  * @return One of the following:\r
 104  * - #IOT_TASKPOOL_SUCCESS\r
 105  * - #IOT_TASKPOOL_BAD_PARAMETER\r
 106  * - #IOT_TASKPOOL_NO_MEMORY\r
 107  *\r
 108  * @warning This function should be called only once. Calling this function more that once will result in\r
 109  * undefined behavior.\r
 110  *\r
 111  */\r
 112 /* @[declare_taskpool_createsystemtaskpool] */\r
 113 IotTaskPoolError_t IotTaskPool_CreateSystemTaskPool( const IotTaskPoolInfo_t * const pInfo );\r
 114 /* @[declare_taskpool_createsystemtaskpool] */\r
 115 \r
 116 /**\r
 117  * @brief Retrieves the one and only instance of a system task pool\r
 118  *\r
 119  * This function retrieves the system task pool created with @ref IotTaskPool_CreateSystemTaskPool, and it is functionally\r
 120  * equivalent to using the shortcut @ref IOT_SYSTEM_TASKPOOL.\r
 121  *\r
 122  * @return The system task pool handle.\r
 123  *\r
 124  * @warning This function should be called after creating the system task pool with @ref IotTaskPool_CreateSystemTaskPool.\r
 125  * Calling this function before creating the system task pool may return a pointer to an uninitialized task pool, NULL, or otherwise\r
 126  * fail with undefined behaviour.\r
 127  *\r
 128  */\r
 129 /* @[declare_taskpool_getsystemtaskpool] */\r
 130 IotTaskPool_t IotTaskPool_GetSystemTaskPool( void );\r
 131 /* @[declare_taskpool_getsystemtaskpool] */\r
 132 \r
 133 /**\r
 134  * @brief Creates one instance of a task pool.\r
 135  *\r
 136  * This function should be called by the user to initialize one instance of a task\r
 137  * pool. The task pool instance will be created around the storage pointed to by the `pTaskPool`\r
 138  * parameter. This function will create the minimum number of threads requested by the user\r
 139  * through an instance of the #IotTaskPoolInfo_t type specified with the `pInfo` parameter.\r
 140  * This function does not allocate memory to hold the task pool data structures and state, but it\r
 141  * may allocates memory to hold the dependent data structures, e.g. the threads of the task\r
 142  * pool.\r
 143  *\r
 144  * @param[in] pInfo A pointer to the task pool initialization data.\r
 145  * @param[out] pTaskPool A pointer to the task pool handle to be used after initialization.\r
 146  * The pointer `pTaskPool` will hold a valid handle only if (@ref IotTaskPool_Create)\r
 147  * completes successfully.\r
 148  *\r
 149  * @return One of the following:\r
 150  * - #IOT_TASKPOOL_SUCCESS\r
 151  * - #IOT_TASKPOOL_BAD_PARAMETER\r
 152  * - #IOT_TASKPOOL_NO_MEMORY\r
 153  *\r
 154  */\r
 155 /* @[declare_taskpool_create] */\r
 156 IotTaskPoolError_t IotTaskPool_Create( const IotTaskPoolInfo_t * const pInfo,\r
 157                                        IotTaskPool_t * const pTaskPool );\r
 158 /* @[declare_taskpool_create] */\r
 159 \r
 160 /**\r
 161  * @brief Destroys a task pool instance and collects all memory associated with a task pool and its\r
 162  * satellite data structures.\r
 163  *\r
 164  * This function should be called to destroy one instance of a task pool previously created with a call\r
 165  * to @ref IotTaskPool_Create or @ref IotTaskPool_CreateSystemTaskPool.\r
 166  * Calling this fuction release all underlying resources. After calling this function, any job scheduled but not yet executed\r
 167  * will be cancelled and destroyed.\r
 168  * The `taskPool` instance will no longer be valid after this function returns.\r
 169  *\r
 170  * @param[in] taskPool A handle to the task pool, e.g. as returned by a call to @ref IotTaskPool_Create or\r
 171  * @ref IotTaskPool_CreateSystemTaskPool. The `taskPool` instance will no longer be valid after this function returns.\r
 172  *\r
 173  * @return One of the following:\r
 174  * - #IOT_TASKPOOL_SUCCESS\r
 175  * - #IOT_TASKPOOL_BAD_PARAMETER\r
 176  *\r
 177  */\r
 178 /* @[declare_taskpool_destroy] */\r
 179 IotTaskPoolError_t IotTaskPool_Destroy( IotTaskPool_t taskPool );\r
 180 /* @[declare_taskpool_destroy] */\r
 181 \r
 182 /**\r
 183  * @brief Sets the maximum number of threads for one instance of a task pool.\r
 184  *\r
 185  * This function sets the maximum number of threads for the task pool\r
 186  * pointed to by `taskPool`.\r
 187  *\r
 188  * If the number of currently active threads in the task pool is greater than `maxThreads`, this\r
 189  * function causes the task pool to shrink the number of active threads.\r
 190  *\r
 191  * @param[in] taskPool A handle to the task pool that must have been previously initialized with\r
 192  * a call to @ref IotTaskPool_Create or @ref IotTaskPool_CreateSystemTaskPool.\r
 193  * @param[in] maxThreads The maximum number of threads for the task pool.\r
 194  *\r
 195  * @return One of the following:\r
 196  * - #IOT_TASKPOOL_SUCCESS\r
 197  * - #IOT_TASKPOOL_BAD_PARAMETER\r
 198  * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS\r
 199  *\r
 200  */\r
 201 /* @[declare_taskpool_setmaxthreads] */\r
 202 IotTaskPoolError_t IotTaskPool_SetMaxThreads( IotTaskPool_t taskPool,\r
 203                                               uint32_t maxThreads );\r
 204 /* @[declare_taskpool_setmaxthreads] */\r
 205 \r
 206 /**\r
 207  * @brief Creates a job for the task pool around a user-provided storage.\r
 208  *\r
 209  * This function may allocate memory to hold the state for a job.\r
 210  *\r
 211  * @param[in] userCallback A user-specified callback for the job.\r
 212  * @param[in] pUserContext A user-specified context for the callback.\r
 213  * @param[in] pJobStorage The storage for the job data structure.\r
 214  * @param[out] pJob A pointer to an instance of @ref IotTaskPoolJob_t that will be initialized when this\r
 215  * function returns successfully. This handle can be used to inspect the job status with\r
 216  * @ref IotTaskPool_GetStatus or cancel the job with @ref IotTaskPool_TryCancel, etc....\r
 217  *\r
 218  * @return One of the following:\r
 219  * - #IOT_TASKPOOL_SUCCESS\r
 220  * - #IOT_TASKPOOL_BAD_PARAMETER\r
 221  *\r
 222  *\r
 223  */\r
 224 /* @[declare_taskpool_createjob] */\r
 225 IotTaskPoolError_t IotTaskPool_CreateJob( IotTaskPoolRoutine_t userCallback,\r
 226                                           void * pUserContext,\r
 227                                           IotTaskPoolJobStorage_t * const pJobStorage,\r
 228                                           IotTaskPoolJob_t * const pJob );\r
 229 /* @[declare_taskpool_createjob] */\r
 230 \r
 231 /**\r
 232  * brief Creates a job for the task pool by allocating the job dynamically.\r
 233  *\r
 234  * A recyclable job does not need to be allocated twice, but it can rather be reused through\r
 235  * subsequent calls to @ref IotTaskPool_CreateRecyclableJob.\r
 236  *\r
 237  * @param[in] taskPool A handle to the task pool for which to create a recyclable job.\r
 238  * @param[in] userCallback A user-specified callback for the job.\r
 239  * @param[in] pUserContext A user-specified context for the callback.\r
 240  * @param[out] pJob A pointer to an instance of @ref IotTaskPoolJob_t that will be initialized when this\r
 241  * function returns successfully. This handle can be used to inspect the job status with\r
 242  * @ref IotTaskPool_GetStatus or cancel the job with @ref IotTaskPool_TryCancel, etc....\r
 243  *\r
 244  * @return One of the following:\r
 245  * - #IOT_TASKPOOL_SUCCESS\r
 246  * - #IOT_TASKPOOL_BAD_PARAMETER\r
 247  * - #IOT_TASKPOOL_NO_MEMORY\r
 248  * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS\r
 249  *\r
 250  * @note This function will not allocate memory.\r
 251  *\r
 252  * @warning A recyclable job should be recycled with a call to @ref IotTaskPool_RecycleJob rather than destroyed.\r
 253  *\r
 254  */\r
 255 /* @[declare_taskpool_createrecyclablejob] */\r
 256 IotTaskPoolError_t IotTaskPool_CreateRecyclableJob( IotTaskPool_t taskPool,\r
 257                                                     IotTaskPoolRoutine_t userCallback,\r
 258                                                     void * pUserContext,\r
 259                                                     IotTaskPoolJob_t * const pJob );\r
 260 /* @[declare_taskpool_createrecyclablejob] */\r
 261 \r
 262 /**\r
 263  * brief Creates a job for the system task pool by allocating the job dynamically.\r
 264  * The system task pool is the task pool created by @ref IotTaskPool_CreateSystemTaskPool.\r
 265  *\r
 266  * A recyclable job does not need to be allocated twice, but it can rather be reused through\r
 267  * subsequent calls to @ref IotTaskPool_CreateRecyclableJob.\r
 268  *\r
 269  * @param[in] userCallback A user-specified callback for the job.\r
 270  * @param[in] pUserContext A user-specified context for the callback.\r
 271  * @param[out] pJob A pointer to an instance of @ref IotTaskPoolJob_t that will be initialized when this\r
 272  * function returns successfully. This handle can be used to inspect the job status with\r
 273  * @ref IotTaskPool_GetStatus or cancel the job with @ref IotTaskPool_TryCancel, etc....\r
 274  *\r
 275  * @return One of the following:\r
 276  * - #IOT_TASKPOOL_SUCCESS\r
 277  * - #IOT_TASKPOOL_BAD_PARAMETER\r
 278  * - #IOT_TASKPOOL_NO_MEMORY\r
 279  * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS\r
 280  *\r
 281  * @note This function will not allocate memory.\r
 282  *\r
 283  * @warning A recyclable job should be recycled with a call to @ref IotTaskPool_RecycleJob rather than destroyed.\r
 284  *\r
 285  */\r
 286 /* @[declare_taskpool_createrecyclablesystemjob] */\r
 287 IotTaskPoolError_t IotTaskPool_CreateRecyclableSystemJob( IotTaskPoolRoutine_t userCallback,\r
 288                                                           void * pUserContext,\r
 289                                                           IotTaskPoolJob_t * const pJob );\r
 290 /* @[declare_taskpool_createrecyclablesystemjob] */\r
 291 \r
 292 /**\r
 293  * @brief This function un-initializes a job.\r
 294  *\r
 295  * This function will destroy a job created with @ref IotTaskPool_CreateRecyclableJob.\r
 296  * A job should not be destroyed twice. A job that was previously scheduled but has not completed yet should not be destroyed,\r
 297  * but rather the application should attempt to cancel it first by calling @ref IotTaskPool_TryCancel.\r
 298  * An attempt to destroy a job that was scheduled but not yet executed or canceled, may result in a\r
 299  * @ref IOT_TASKPOOL_ILLEGAL_OPERATION error.\r
 300  *\r
 301  * @param[in] taskPool A handle to the task pool, e.g. as returned by a call to @ref IotTaskPool_Create or @ref IotTaskPool_CreateSystemTaskPool.\r
 302  * @param[in] job A handle to a job that was create with a call to @ref IotTaskPool_CreateJob.\r
 303  *\r
 304  * @return One of the following:\r
 305  * - #IOT_TASKPOOL_SUCCESS\r
 306  * - #IOT_TASKPOOL_BAD_PARAMETER\r
 307  * - #IOT_TASKPOOL_ILLEGAL_OPERATION\r
 308  * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS\r
 309  *\r
 310  * @warning The task pool will try and prevent destroying jobs that are currently queued for execution, but does\r
 311  * not enforce strict ordering of operations. It is up to the user to make sure @ref IotTaskPool_DestroyRecyclableJob is not called\r
 312  * our of order.\r
 313  *\r
 314  * @warning Calling this function on job that was not previously created with @ref IotTaskPool_CreateRecyclableJob\r
 315  * will result in a @ref IOT_TASKPOOL_ILLEGAL_OPERATION error.\r
 316  *\r
 317  */\r
 318 /* @[declare_taskpool_destroyrecyclablejob] */\r
 319 IotTaskPoolError_t IotTaskPool_DestroyRecyclableJob( IotTaskPool_t taskPool,\r
 320                                                      IotTaskPoolJob_t job );\r
 321 /* @[declare_taskpool_destroyrecyclablejob] */\r
 322 \r
 323 /**\r
 324  * @brief Recycles a job into the task pool job cache.\r
 325  *\r
 326  * This function will try and recycle the job into the task pool cache. If the cache is full,\r
 327  * the job memory is destroyed as if the user called @ref IotTaskPool_DestroyRecyclableJob. The job should be recycled into\r
 328  * the task pool instance from where it was allocated.\r
 329  * Failure to do so will yield undefined results. A job should not be recycled twice. A job\r
 330  * that was previously scheduled but not completed or canceled cannot be safely recycled. An attempt to do so will result\r
 331  * in an @ref IOT_TASKPOOL_ILLEGAL_OPERATION error.\r
 332  *\r
 333  * @param[in] taskPool A handle to the task pool, e.g. as returned by a call to @ref IotTaskPool_Create.\r
 334  * @param[out] job A pointer to a job that was create with a call to @ref IotTaskPool_CreateJob.\r
 335  *\r
 336  * @return One of the following:\r
 337  * - #IOT_TASKPOOL_SUCCESS\r
 338  * - #IOT_TASKPOOL_BAD_PARAMETER\r
 339  * - #IOT_TASKPOOL_ILLEGAL_OPERATION\r
 340  * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS\r
 341  *\r
 342  * @warning The `taskPool` used in this function should be the same\r
 343  * used to create the job pointed to by `job`, or the results will be undefined.\r
 344  *\r
 345  * @warning Attempting to call this function on a statically allocated job will result in @ref IOT_TASKPOOL_ILLEGAL_OPERATION\r
 346  * error.\r
 347  *\r
 348  * @warning This function should be used to recycle a job in the task pool cache when after the job executed.\r
 349  * Failing to call either this function or @ref IotTaskPool_DestroyRecyclableJob will result is a memory leak. Statically\r
 350  * allocated jobs do not need to be recycled or destroyed.\r
 351  *\r
 352  */\r
 353 /* @[declare_taskpool_recyclejob] */\r
 354 IotTaskPoolError_t IotTaskPool_RecycleJob( IotTaskPool_t taskPool,\r
 355                                            IotTaskPoolJob_t job );\r
 356 /* @[declare_taskpool_recyclejob] */\r
 357 \r
 358 /**\r
 359  * @brief This function schedules a job created with @ref IotTaskPool_CreateJob or @ref IotTaskPool_CreateRecyclableJob\r
 360  * against the task pool pointed to by `taskPool`.\r
 361  *\r
 362  * See @ref taskpool_design for a description of the jobs lifetime and interaction with the threads used in the task pool\r
 363  * library.\r
 364  *\r
 365  * @param[in] taskPool A handle to the task pool that must have been previously initialized with.\r
 366  * a call to @ref IotTaskPool_Create.\r
 367  * @param[in] job A job to schedule for execution. This must be first initialized with a call to @ref IotTaskPool_CreateJob.\r
 368  * @param[in] flags Flags to be passed by the user, e.g. to identify the job as high priority by specifying #IOT_TASKPOOL_JOB_HIGH_PRIORITY.\r
 369  *\r
 370  * @return One of the following:\r
 371  * - #IOT_TASKPOOL_SUCCESS\r
 372  * - #IOT_TASKPOOL_BAD_PARAMETER\r
 373  * - #IOT_TASKPOOL_ILLEGAL_OPERATION\r
 374  * - #IOT_TASKPOOL_NO_MEMORY\r
 375  * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS\r
 376  *\r
 377  *\r
 378  * @note This function will not allocate memory, so it is guaranteed to succeed if the paramters are correct and the task pool\r
 379  * was correctly initialized, and not yet destroyed.\r
 380  *\r
 381  * @warning The `taskPool` used in this function should be the same used to create the job pointed to by `job`, or the\r
 382  * results will be undefined.\r
 383  *\r
 384  * <b>Example</b>\r
 385  * @code{c}\r
 386  * // An example of a user context to pass to a callback through a task pool thread.\r
 387  * typedef struct JobUserContext\r
 388  * {\r
 389  *     uint32_t counter;\r
 390  * } JobUserContext_t;\r
 391  *\r
 392  * // An example of a user callback to invoke through a task pool thread.\r
 393  * static void ExecutionCb( IotTaskPool_t taskPool, IotTaskPoolJob_t job, void * context )\r
 394  * {\r
 395  *     ( void )taskPool;\r
 396  *     ( void )job;\r
 397  *\r
 398  *     JobUserContext_t * pUserContext = ( JobUserContext_t * )context;\r
 399  *\r
 400  *     pUserContext->counter++;\r
 401  * }\r
 402  *\r
 403  * void TaskPoolExample( )\r
 404  * {\r
 405  *     JobUserContext_t userContext = { 0 };\r
 406  *     IotTaskPoolJob_t job;\r
 407  *     IotTaskPool_t taskPool;\r
 408  *\r
 409  *     // Configure the task pool to hold at least two threads and three at the maximum.\r
 410  *     // Provide proper stack size and priority per the application needs.\r
 411  *\r
 412  *     const IotTaskPoolInfo_t tpInfo = { .minThreads = 2, .maxThreads = 3, .stackSize = 512, .priority = 0 };\r
 413  *\r
 414  *     // Create a task pool.\r
 415  *     IotTaskPool_Create( &tpInfo, &taskPool );\r
 416  *\r
 417  *     // Statically allocate one job, schedule it.\r
 418  *     IotTaskPool_CreateJob( &ExecutionCb, &userContext, &job );\r
 419  *\r
 420  *     IotTaskPoolError_t errorSchedule = IotTaskPool_Schedule( taskPool, &job, 0 );\r
 421  *\r
 422  *     switch ( errorSchedule )\r
 423  *     {\r
 424  *     case IOT_TASKPOOL_SUCCESS:\r
 425  *         break;\r
 426  *     case IOT_TASKPOOL_BAD_PARAMETER:          // Invalid parameters, such as a NULL handle, can trigger this error.\r
 427  *     case IOT_TASKPOOL_ILLEGAL_OPERATION:      // Scheduling a job that was previously scheduled or destroyed could trigger this error.\r
 428  *     case IOT_TASKPOOL_NO_MEMORY:              // Scheduling a with flag #IOT_TASKPOOL_JOB_HIGH_PRIORITY could trigger this error.\r
 429  *     case IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS:   // Scheduling a job after trying to destroy the task pool could trigger this error.\r
 430  *         // ASSERT\r
 431  *         break;\r
 432  *     default:\r
 433  *         // ASSERT\r
 434  *     }\r
 435  *\r
 436  *     //\r
 437  *     // ... Perform other operations ...\r
 438  *     //\r
 439  *\r
 440  *     IotTaskPool_Destroy( taskPool );\r
 441  * }\r
 442  * @endcode\r
 443  */\r
 444 /* @[declare_taskpool_schedule] */\r
 445 IotTaskPoolError_t IotTaskPool_Schedule( IotTaskPool_t taskPool,\r
 446                                          IotTaskPoolJob_t job,\r
 447                                          uint32_t flags );\r
 448 \r
 449 /**\r
 450  * @brief This function schedules a job created with @ref IotTaskPool_CreateJob or @ref IotTaskPool_CreateRecyclableJob @ref IotTaskPool_CreateRecyclableSystemJob\r
 451  * against the system task pool.  The system task pool is the task pool created by @ref IotTaskPool_CreateSystemTaskPool.\r
 452  *\r
 453  * See @ref taskpool_design for a description of the jobs lifetime and interaction with the threads used in the task pool\r
 454  * library.\r
 455  *\r
 456  * @param[in] job A job to schedule for execution. This must be first initialized with a call to @ref IotTaskPool_CreateJob.\r
 457  * @param[in] flags Flags to be passed by the user, e.g. to identify the job as high priority by specifying #IOT_TASKPOOL_JOB_HIGH_PRIORITY.\r
 458  *\r
 459  * @return One of the following:\r
 460  * - #IOT_TASKPOOL_SUCCESS\r
 461  * - #IOT_TASKPOOL_BAD_PARAMETER\r
 462  * - #IOT_TASKPOOL_ILLEGAL_OPERATION\r
 463  * - #IOT_TASKPOOL_NO_MEMORY\r
 464  * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS\r
 465  *\r
 466  *\r
 467  * @note This function will not allocate memory, so it is guaranteed to succeed if the parameters are correct and the task pool\r
 468  * was correctly initialized, and not yet destroyed.\r
 469  *\r
 470  * <b>Example</b>\r
 471  * @code{c}\r
 472  * // An example of a user context to pass to a callback through a task pool thread.\r
 473  * typedef struct JobUserContext\r
 474  * {\r
 475  *     uint32_t counter;\r
 476  * } JobUserContext_t;\r
 477  *\r
 478  * // An example of a user callback to invoke through a task pool thread.\r
 479  * static void ExecutionCb( IotTaskPool_t taskPool, IotTaskPoolJob_t job, void * context )\r
 480  * {\r
 481  *     ( void )taskPool;\r
 482  *     ( void )job;\r
 483  *\r
 484  *     JobUserContext_t * pUserContext = ( JobUserContext_t * )context;\r
 485  *\r
 486  *     pUserContext->counter++;\r
 487  * }\r
 488  *\r
 489  * void TaskPoolExample( )\r
 490  * {\r
 491  *     JobUserContext_t userContext = { 0 };\r
 492  *     IotTaskPoolJob_t job;\r
 493  *\r
 494  *     // Create the system task pool.  This example assumes the task pool is created successfully.\r
 495  *     // It is recommended to test the function's return value in production code.\r
 496  *     IotTaskPool_CreateSystemTaskPool( &xTaskPoolParameters );\r
 497  *\r
 498  *     // Statically allocate one job, schedule it.\r
 499  *     IotTaskPool_CreateJob( &ExecutionCb, &userContext, &job );\r
 500  *\r
 501  *     IotTaskPoolError_t errorSchedule = IotTaskPool_ScheduleSystemJob( &job, 0 );\r
 502  *\r
 503  *     switch ( errorSchedule )\r
 504  *     {\r
 505  *     case IOT_TASKPOOL_SUCCESS:\r
 506  *         break;\r
 507  *     case IOT_TASKPOOL_BAD_PARAMETER:          // Invalid parameters, such as a NULL handle, can trigger this error.\r
 508  *     case IOT_TASKPOOL_ILLEGAL_OPERATION:      // Scheduling a job that was previously scheduled or destroyed could trigger this error.\r
 509  *     case IOT_TASKPOOL_NO_MEMORY:              // Scheduling a with flag #IOT_TASKPOOL_JOB_HIGH_PRIORITY could trigger this error.\r
 510  *     case IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS:   // Scheduling a job after trying to destroy the task pool could trigger this error.\r
 511  *         // ASSERT\r
 512  *         break;\r
 513  *     default:\r
 514  *         // ASSERT\r
 515  *     }\r
 516  *\r
 517  *     //\r
 518  *     // ... Perform other operations ...\r
 519  *     //\r
 520  *\r
 521  *     IotTaskPool_Destroy( taskPool );\r
 522  * }\r
 523  * @endcode\r
 524  */\r
 525 /* @[declare_taskpool_schedulesystemjob] */\r
 526 IotTaskPoolError_t IotTaskPool_ScheduleSystemJob( IotTaskPoolJob_t pJob,\r
 527                                                uint32_t flags );\r
 528 \r
 529 /* @[declare_taskpool_schedulesystemjob] */\r
 530 \r
 531 /**\r
 532  * @brief This function schedules a job created with @ref IotTaskPool_CreateJob against the task pool\r
 533  * pointed to by `taskPool` to be executed after a user-defined time interval.\r
 534  *\r
 535  * See @ref taskpool_design for a description of the jobs lifetime and interaction with the threads used in the task pool\r
 536  * library.\r
 537  *\r
 538  * @param[in] taskPool A handle to the task pool that must have been previously initialized with.\r
 539  * a call to @ref IotTaskPool_Create.\r
 540  * @param[in] job A job to schedule for execution. This must be first initialized with a call to @ref IotTaskPool_CreateJob.\r
 541  * @param[in] timeMs The time in milliseconds to wait before scheduling the job.\r
 542  *\r
 543  * @return One of the following:\r
 544  * - #IOT_TASKPOOL_SUCCESS\r
 545  * - #IOT_TASKPOOL_BAD_PARAMETER\r
 546  * - #IOT_TASKPOOL_ILLEGAL_OPERATION\r
 547  * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS\r
 548  *\r
 549  *\r
 550  * @note This function will not allocate memory.\r
 551  *\r
 552  * @warning The `taskPool` used in this function should be the same\r
 553  * used to create the job pointed to by `job`, or the results will be undefined.\r
 554  *\r
 555  */\r
 556 /* @[declare_taskpool_scheduledeferred] */\r
 557 IotTaskPoolError_t IotTaskPool_ScheduleDeferred( IotTaskPool_t taskPool,\r
 558                                                  IotTaskPoolJob_t job,\r
 559                                                  uint32_t timeMs );\r
 560 /* @[declare_taskpool_scheduledeferred] */\r
 561 \r
 562 /**\r
 563  * @brief This function retrieves the current status of a job.\r
 564  *\r
 565  * @param[in] taskPool A handle to the task pool that must have been previously initialized with\r
 566  * a call to @ref IotTaskPool_Create or @ref IotTaskPool_CreateSystemTaskPool.\r
 567  * @param[in] job The job to cancel.\r
 568  * @param[out] pStatus The status of the job at the time of cancellation.\r
 569  *\r
 570  * @return One of the following:\r
 571  * - #IOT_TASKPOOL_SUCCESS\r
 572  * - #IOT_TASKPOOL_BAD_PARAMETER\r
 573  * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS\r
 574  *\r
 575  * @warning This function is not thread safe and the job status returned in `pStatus` may be invalid by the time\r
 576  * the calling thread has a chance to inspect it.\r
 577  */\r
 578 /* @[declare_taskpool_getstatus] */\r
 579 IotTaskPoolError_t IotTaskPool_GetStatus( IotTaskPool_t taskPool,\r
 580                                           IotTaskPoolJob_t job,\r
 581                                           IotTaskPoolJobStatus_t * const pStatus );\r
 582 /* @[declare_taskpool_getstatus] */\r
 583 \r
 584 /**\r
 585  * @brief This function tries to cancel a job that was previously scheduled with @ref IotTaskPool_Schedule.\r
 586  *\r
 587  * A job can be canceled only if it is not yet executing, i.e. if its status is\r
 588  * @ref IOT_TASKPOOL_STATUS_READY or @ref IOT_TASKPOOL_STATUS_SCHEDULED. Calling\r
 589  * @ref IotTaskPool_TryCancel on a job whose status is @ref IOT_TASKPOOL_STATUS_COMPLETED,\r
 590  * or #IOT_TASKPOOL_STATUS_CANCELED will yield a #IOT_TASKPOOL_CANCEL_FAILED return result.\r
 591  *\r
 592  * @param[in] taskPool A handle to the task pool that must have been previously initialized with\r
 593  * a call to @ref IotTaskPool_Create.\r
 594  * @param[in] job The job to cancel.\r
 595  * @param[out] pStatus The status of the job at the time of cancellation.\r
 596  *\r
 597  * @return One of the following:\r
 598  * - #IOT_TASKPOOL_SUCCESS\r
 599  * - #IOT_TASKPOOL_BAD_PARAMETER\r
 600  * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS\r
 601  * - #IOT_TASKPOOL_CANCEL_FAILED\r
 602  *\r
 603  * @warning The `taskPool` used in this function should be the same\r
 604  * used to create the job pointed to by `job`, or the results will be undefined.\r
 605  *\r
 606  */\r
 607 /* @[declare_taskpool_trycancel] */\r
 608 IotTaskPoolError_t IotTaskPool_TryCancel( IotTaskPool_t taskPool,\r
 609                                           IotTaskPoolJob_t job,\r
 610                                           IotTaskPoolJobStatus_t * const pStatus );\r
 611 /* @[declare_taskpool_trycancel] */\r
 612 \r
 613 /**\r
 614  * @brief Returns a pointer to the job storage from an instance of a job handle\r
 615  * of type @ref IotTaskPoolJob_t. This function is guaranteed to succeed for a\r
 616  * valid job handle.\r
 617  *\r
 618  * @param[in] job The job handle.\r
 619  *\r
 620  * @return A pointer to the storage associated with the job handle `job`.\r
 621  *\r
 622  * @warning If the `job` handle used is invalid, the results will be undefined.\r
 623  */\r
 624 /* @[declare_taskpool_getjobstoragefromhandle] */\r
 625 IotTaskPoolJobStorage_t * IotTaskPool_GetJobStorageFromHandle( IotTaskPoolJob_t job );\r
 626 /* @[declare_taskpool_getjobstoragefromhandle] */\r
 627 \r
 628 /**\r
 629  * @brief Returns a string that describes an @ref IotTaskPoolError_t.\r
 630  *\r
 631  * Like the POSIX's `strerror`, this function returns a string describing a\r
 632  * return code. In this case, the return code is a task pool library error code,\r
 633  * `status`.\r
 634  *\r
 635  * The string returned by this function <b>MUST</b> be treated as read-only: any\r
 636  * attempt to modify its contents may result in a crash. Therefore, this function\r
 637  * is limited to usage in logging.\r
 638  *\r
 639  * @param[in] status The status to describe.\r
 640  *\r
 641  * @return A read-only string that describes `status`.\r
 642  *\r
 643  * @warning The string returned by this function must never be modified.\r
 644  */\r
 645 /* @[declare_taskpool_strerror] */\r
 646 const char * IotTaskPool_strerror( IotTaskPoolError_t status );\r
 647 /* @[declare_taskpool_strerror] */\r
 648 \r
 649 /**\r
 650  * @brief The maximum number of task pools to be created when using\r
 651  * a memory pool.\r
 652  */\r
 653 #ifndef IOT_TASKPOOLS\r
 654 #define IOT_TASKPOOLS                          ( 4 )\r
 655 #endif\r
 656 \r
 657 /**\r
 658  * @brief The maximum number of jobs to cache.\r
 659  */\r
 660 #ifndef IOT_TASKPOOL_JOBS_RECYCLE_LIMIT\r
 661     #define IOT_TASKPOOL_JOBS_RECYCLE_LIMIT    ( 8UL )\r
 662 #endif\r
 663 \r
 664 /**\r
 665  * @brief The maximum timeout in milliseconds to wait for a job to be scheduled before waking up a worker thread.\r
 666  * A worker thread that wakes up as a result of a timeout may exit to allow the task pool to fold back to its\r
 667  * minimum number of threads.\r
 668  */\r
 669 #ifndef IOT_TASKPOOL_JOB_WAIT_TIMEOUT_MS\r
 670     #define IOT_TASKPOOL_JOB_WAIT_TIMEOUT_MS    ( 60 * 1000UL )\r
 671 #endif\r
 672 \r
 673 #endif /* ifndef IOT_TASKPOOL_H_ */\r