git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Source/FreeRTOS-IoT-Libraries/abstractions/platform/freertos/include/iot_taskpool_freertos.h

   1 /*\r
   2  * IoT Common V1.0.0\r
   3  * Copyright (C) 2019 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 \r
  23 /**\r
  24  * @file iot_taskpool.h\r
  25  * @brief User-facing functions of the task pool library.\r
  26  */\r
  27 \r
  28 #ifndef IOT_TASKPOOL_H_\r
  29 #define IOT_TASKPOOL_H_\r
  30 \r
  31 /* The config header is always included first. */\r
  32 #include "iot_config.h"\r
  33 \r
  34 /* Standard includes. */\r
  35 #include <stdbool.h>\r
  36 #include <stdint.h>\r
  37 #include <stddef.h>\r
  38 \r
  39 /* Task pool types. */\r
  40 #include "types/iot_taskpool_types_freertos.h"\r
  41 \r
  42 /*------------------------- Task Pool library functions --------------------------*/\r
  43 \r
  44 /**\r
  45  * @functionspage{taskpool,task pool library}\r
  46  * - @functionname{taskpool_function_createsystemtaskpool}\r
  47  * - @functionname{taskpool_function_createjob}\r
  48  * - @functionname{taskpool_function_schedule}\r
  49  * - @functionname{taskpool_function_scheduledeferred}\r
  50  * - @functionname{taskpool_function_getstatus}\r
  51  * - @functionname{taskpool_function_trycancel}\r
  52  * - @functionname{taskpool_function_getjobstoragefromhandle}\r
  53  * - @functionname{taskpool_function_strerror}\r
  54  */\r
  55 \r
  56 /**\r
  57  * @functionpage{IotTaskPool_CreateSystemTaskPool,taskpool,createsystemtaskpool}\r
  58  * @functionpage{IotTaskPool_CreateJob,taskpool,createjob}\r
  59  * @functionpage{IotTaskPool_Schedule,taskpool,schedule}\r
  60  * @functionpage{IotTaskPool_ScheduleDeferred,taskpool,scheduledeferred}\r
  61  * @functionpage{IotTaskPool_GetStatus,taskpool,getstatus}\r
  62  * @functionpage{IotTaskPool_TryCancel,taskpool,trycancel}\r
  63  * @functionpage{IotTaskPool_GetJobStorageFromHandle,taskpool,getjobstoragefromhandle}\r
  64  * @functionpage{IotTaskPool_strerror,taskpool,strerror}\r
  65  */\r
  66 \r
  67 /**\r
  68  * @brief Creates the one single instance of the system task pool.\r
  69  *\r
  70  * This function should be called once by the application to initialize the one single instance of the system task pool.\r
  71  * An application should initialize the system task pool early in the boot sequence, before initializing any other library\r
  72  * (e.g. MQTT) that uses the system task pool. An application should also initialize the system\r
  73  * task pool before posting any jobs. Early initialization is typically easy to accomplish by creating the system task pool\r
  74  * before the scheduler is started.\r
  75  *\r
  76  * The shortcut @ref IOT_SYSTEM_TASKPOOL contains the system task pool handle.\r
  77  *\r
  78  * @param[in] pInfo A pointer to the task pool initialization data.\r
  79  *\r
  80  * @return One of the following:\r
  81  * - #IOT_TASKPOOL_SUCCESS\r
  82  * - #IOT_TASKPOOL_BAD_PARAMETER\r
  83  * - #IOT_TASKPOOL_NO_MEMORY\r
  84  *\r
  85  * @warning This function should be called only once. Calling this function more that once will result in\r
  86  * undefined behavior.\r
  87  *\r
  88  */\r
  89 /* @[declare_taskpool_createsystemtaskpool] */\r
  90 IotTaskPoolError_t IotTaskPool_CreateSystemTaskPool( const IotTaskPoolInfo_t * const pInfo );\r
  91 /* @[declare_taskpool_createsystemtaskpool] */\r
  92 \r
  93 /**\r
  94  * @brief Creates a job for the task pool around a user-provided storage.\r
  95  *\r
  96  * @param[in] userCallback A user-specified callback for the job.\r
  97  * @param[in] pUserContext A user-specified context for the callback.\r
  98  * @param[in,out] pJobStorage The storage for the job data structure.\r
  99  * @param[out] pJob A pointer to an instance of @ref IotTaskPoolJob_t that will be initialized when this\r
 100  * function returns successfully. This handle can be used to inspect the job status with\r
 101  * @ref IotTaskPool_GetStatus or cancel the job with @ref IotTaskPool_TryCancel, etc....\r
 102  *\r
 103  * @return One of the following:\r
 104  * - #IOT_TASKPOOL_SUCCESS\r
 105  * - #IOT_TASKPOOL_BAD_PARAMETER\r
 106  *\r
 107  *\r
 108  */\r
 109 /* @[declare_taskpool_createjob] */\r
 110 IotTaskPoolError_t IotTaskPool_CreateJob( IotTaskPoolRoutine_t userCallback,\r
 111                                           void * pUserContext,\r
 112                                           IotTaskPoolJobStorage_t * const pJobStorage,\r
 113                                           IotTaskPoolJob_t * const pJob );\r
 114 /* @[declare_taskpool_createjob] */\r
 115 \r
 116 /**\r
 117  * @brief This function schedules a job created with @ref IotTaskPool_CreateJob against the task pool pointed to by `taskPool`.\r
 118  *\r
 119  * @param[in] taskPool A handle to an initialized taskpool.\r
 120  * @param[in] job A job to schedule for execution. This must be first initialized with a call to @ref IotTaskPool_CreateJob.\r
 121  * @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
 122  *\r
 123  * @return One of the following:\r
 124  * - #IOT_TASKPOOL_SUCCESS\r
 125  * - #IOT_TASKPOOL_BAD_PARAMETER\r
 126  * - #IOT_TASKPOOL_ILLEGAL_OPERATION\r
 127  * - #IOT_TASKPOOL_NO_MEMORY\r
 128  * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS\r
 129  *\r
 130  * @note This function will not allocate memory, so it is guaranteed to succeed if the parameters are correct and the task pool\r
 131  * was correctly initialized, and not yet destroyed.\r
 132  *\r
 133  * <b>Example</b>\r
 134  * @code{c}\r
 135  * // An example of a user context to pass to a callback through a task pool thread.\r
 136  * typedef struct JobUserContext\r
 137  * {\r
 138  *     uint32_t counter;\r
 139  * } JobUserContext_t;\r
 140  *\r
 141  * // An example of a user callback to invoke through a task pool thread.\r
 142  * static void ExecutionCb( IotTaskPool_t taskPool, IotTaskPoolJob_t job, void * context )\r
 143  * {\r
 144  *     ( void )taskPool;\r
 145  *     ( void )job;\r
 146  *\r
 147  *     JobUserContext_t * pUserContext = ( JobUserContext_t * )context;\r
 148  *\r
 149  *     pUserContext->counter++;\r
 150  * }\r
 151  *\r
 152  * void TaskPoolExample( )\r
 153  * {\r
 154  *     JobUserContext_t userContext = { 0 };\r
 155  *     IotTaskPoolJob_t job;\r
 156  *     IotTaskPool_t taskPool;\r
 157  *\r
 158  *     // Configure the task pool to hold one thread.\r
 159  *     // Provide proper stack size and priority per the application needs.\r
 160  *\r
 161  *     const IotTaskPoolInfo_t tpInfo = { .minThreads = 1, .maxThreads = 1, .stackSize = 512, .priority = 0 };\r
 162  *\r
 163  *     // Create a task pool.\r
 164  *     IotTaskPool_Create( &tpInfo, &taskPool );\r
 165  *\r
 166  *     // Statically allocate one job, schedule it.\r
 167  *     IotTaskPool_CreateJob( &ExecutionCb, &userContext, &job );\r
 168  *\r
 169  *     IotTaskPoolError_t errorSchedule = IotTaskPool_Schedule( taskPool, &job, 0 );\r
 170  *\r
 171  *     switch ( errorSchedule )\r
 172  *     {\r
 173  *     case IOT_TASKPOOL_SUCCESS:\r
 174  *         break;\r
 175  *     case IOT_TASKPOOL_BAD_PARAMETER:          // Invalid parameters, such as a NULL handle, can trigger this error.\r
 176  *     case IOT_TASKPOOL_ILLEGAL_OPERATION:      // Scheduling a job that was previously scheduled or destroyed could trigger this error.\r
 177  *     case IOT_TASKPOOL_NO_MEMORY:              // Scheduling a with flag #IOT_TASKPOOL_JOB_HIGH_PRIORITY could trigger this error.\r
 178  *     case IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS:   // Scheduling a job after trying to destroy the task pool could trigger this error.\r
 179  *         // ASSERT\r
 180  *         break;\r
 181  *     default:\r
 182  *         // ASSERT\r
 183  *     }\r
 184  *\r
 185  *     //\r
 186  *     // ... Perform other operations ...\r
 187  *     //\r
 188  *\r
 189  *     IotTaskPool_Destroy( taskPool );\r
 190  * }\r
 191  * @endcode\r
 192  */\r
 193 /* @[declare_taskpool_schedule] */\r
 194 IotTaskPoolError_t IotTaskPool_Schedule( IotTaskPool_t taskPool,\r
 195                                          IotTaskPoolJob_t job,\r
 196                                          uint32_t flags );\r
 197 /* @[declare_taskpool_schedule] */\r
 198 \r
 199 /**\r
 200  * @brief This function schedules a job created with @ref IotTaskPool_CreateJob to be executed after a user-defined time interval.\r
 201  *\r
 202  * @param[in] taskPool A handle to an initialized taskpool.\r
 203  * @param[in] job A job to schedule for execution. This must be first initialized with a call to @ref IotTaskPool_CreateJob.\r
 204  * @param[in] timeMs The time in milliseconds to wait before scheduling the job.\r
 205  *\r
 206  * @return One of the following:\r
 207  * - #IOT_TASKPOOL_SUCCESS\r
 208  * - #IOT_TASKPOOL_BAD_PARAMETER\r
 209  * - #IOT_TASKPOOL_ILLEGAL_OPERATION\r
 210  * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS\r
 211  *\r
 212  *\r
 213  * @note This function will not allocate memory.\r
 214  *\r
 215  * @warning The `taskPool` used in this function should be the same\r
 216  * used to create the job pointed to by `job`, or the results will be undefined.\r
 217  *\r
 218  */\r
 219 /* @[declare_taskpool_scheduledeferred] */\r
 220 IotTaskPoolError_t IotTaskPool_ScheduleDeferred( IotTaskPool_t taskPool,\r
 221                                                  IotTaskPoolJob_t job,\r
 222                                                  uint32_t timeMs );\r
 223 /* @[declare_taskpool_scheduledeferred] */\r
 224 \r
 225 /**\r
 226  * @brief This function retrieves the current status of a job.\r
 227  *\r
 228  * @param[in] taskPool A handle to an initialized taskpool.\r
 229  * @param[in] job The job to cancel.\r
 230  * @param[out] pStatus The status of the job at the time of cancellation.\r
 231  *\r
 232  * @return One of the following:\r
 233  * - #IOT_TASKPOOL_SUCCESS\r
 234  * - #IOT_TASKPOOL_BAD_PARAMETER\r
 235  * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS\r
 236  *\r
 237  * @warning This function is not thread safe and the job status returned in `pStatus` may be invalid by the time\r
 238  * the calling thread has a chance to inspect it.\r
 239  */\r
 240 /* @[declare_taskpool_getstatus] */\r
 241 IotTaskPoolError_t IotTaskPool_GetStatus( IotTaskPool_t taskPool,\r
 242                                           IotTaskPoolJob_t job,\r
 243                                           IotTaskPoolJobStatus_t * const pStatus );\r
 244 /* @[declare_taskpool_getstatus] */\r
 245 \r
 246 /**\r
 247  * @brief This function tries to cancel a job that was previously scheduled with @ref IotTaskPool_Schedule.\r
 248  *\r
 249  * A job can be canceled only if it is not yet executing, i.e. if its status is\r
 250  * @ref IOT_TASKPOOL_STATUS_READY or @ref IOT_TASKPOOL_STATUS_SCHEDULED. Calling\r
 251  * @ref IotTaskPool_TryCancel on a job whose status is @ref IOT_TASKPOOL_STATUS_COMPLETED,\r
 252  * or #IOT_TASKPOOL_STATUS_CANCELED will yield a #IOT_TASKPOOL_CANCEL_FAILED return result.\r
 253  *\r
 254  * @param[in] taskPool A handle to an initialized taskpool.\r
 255  * @param[in] job The job to cancel.\r
 256  * @param[out] pStatus The status of the job at the time of cancellation.\r
 257  *\r
 258  * @return One of the following:\r
 259  * - #IOT_TASKPOOL_SUCCESS\r
 260  * - #IOT_TASKPOOL_BAD_PARAMETER\r
 261  * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS\r
 262  * - #IOT_TASKPOOL_CANCEL_FAILED\r
 263  *\r
 264  * @warning The `taskPool` used in this function should be the same\r
 265  * used to create the job pointed to by `job`, or the results will be undefined.\r
 266  *\r
 267  */\r
 268 /* @[declare_taskpool_trycancel] */\r
 269 IotTaskPoolError_t IotTaskPool_TryCancel( IotTaskPool_t taskPool,\r
 270                                           IotTaskPoolJob_t job,\r
 271                                           IotTaskPoolJobStatus_t * const pStatus );\r
 272 /* @[declare_taskpool_trycancel] */\r
 273 \r
 274 /**\r
 275  * @brief Returns a pointer to the job storage from an instance of a job handle\r
 276  * of type @ref IotTaskPoolJob_t. This function is guaranteed to succeed for a\r
 277  * valid job handle.\r
 278  *\r
 279  * @param[in] job The job handle.\r
 280  *\r
 281  * @return A pointer to the storage associated with the job handle `job`.\r
 282  *\r
 283  * @warning If the `job` handle used is invalid, the results will be undefined.\r
 284  */\r
 285 /* @[declare_taskpool_getjobstoragefromhandle] */\r
 286 IotTaskPoolJobStorage_t * IotTaskPool_GetJobStorageFromHandle( IotTaskPoolJob_t job );\r
 287 /* @[declare_taskpool_getjobstoragefromhandle] */\r
 288 \r
 289 /**\r
 290  * @brief Returns a string that describes an @ref IotTaskPoolError_t.\r
 291  *\r
 292  * Like the POSIX's `strerror`, this function returns a string describing a\r
 293  * return code. In this case, the return code is a task pool library error code,\r
 294  * `status`.\r
 295  *\r
 296  * The string returned by this function <b>MUST</b> be treated as read-only: any\r
 297  * attempt to modify its contents may result in a crash. Therefore, this function\r
 298  * is limited to usage in logging.\r
 299  *\r
 300  * @param[in] status The status to describe.\r
 301  *\r
 302  * @return A read-only string that describes `status`.\r
 303  *\r
 304  * @warning The string returned by this function must never be modified.\r
 305  */\r
 306 /* @[declare_taskpool_strerror] */\r
 307 const char * IotTaskPool_strerror( IotTaskPoolError_t status );\r
 308 /* @[declare_taskpool_strerror] */\r
 309 \r
 310 #endif /* ifndef IOT_TASKPOOL_H_ */\r