git.sur5r.net Git - freertos/blob - FreeRTOS-Plus/Source/FreeRTOS-IoT-Libraries/c_sdk/standard/common/include/types/iot_taskpool_types.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_types.h\r
  28  * @brief Types of the task pool.\r
  29  */\r
  30 \r
  31 #ifndef IOT_TASKPOOL_TYPES_H_\r
  32 #define IOT_TASKPOOL_TYPES_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 \r
  41 /* Platform types includes. */\r
  42 #include "types/iot_platform_types.h"\r
  43 \r
  44 /* Linear containers (lists and queues) include. */\r
  45 #include "iot_linear_containers.h"\r
  46 \r
  47 /*-------------------------- Task pool enumerated types --------------------------*/\r
  48 \r
  49 /**\r
  50  * @ingroup taskpool_datatypes_enums\r
  51  * @brief Return codes of [task pool functions](@ref taskpool_functions).\r
  52  */\r
  53 typedef enum IotTaskPoolError\r
  54 {\r
  55     /**\r
  56      * @brief Task pool operation completed successfully.\r
  57      *\r
  58      * Functions that may return this value:\r
  59      * - @ref taskpool_function_createsystemtaskpool\r
  60      * - @ref taskpool_function_create\r
  61      * - @ref taskpool_function_destroy\r
  62      * - @ref taskpool_function_setmaxthreads\r
  63      * - @ref taskpool_function_createjob\r
  64      * - @ref taskpool_function_createrecyclablejob\r
  65      * - @ref taskpool_function_destroyrecyclablejob\r
  66      * - @ref taskpool_function_recyclejob\r
  67      * - @ref taskpool_function_schedule\r
  68      * - @ref taskpool_function_scheduledeferred\r
  69      * - @ref taskpool_function_getstatus\r
  70      * - @ref taskpool_function_trycancel\r
  71      *\r
  72      */\r
  73     IOT_TASKPOOL_SUCCESS = 0,\r
  74 \r
  75     /**\r
  76      * @brief Task pool operation failed because at least one parameter is invalid.\r
  77      *\r
  78      * Functions that may return this value:\r
  79      * - @ref taskpool_function_createsystemtaskpool\r
  80      * - @ref taskpool_function_create\r
  81      * - @ref taskpool_function_destroy\r
  82      * - @ref taskpool_function_setmaxthreads\r
  83      * - @ref taskpool_function_createjob\r
  84      * - @ref taskpool_function_createrecyclablejob\r
  85      * - @ref taskpool_function_destroyrecyclablejob\r
  86      * - @ref taskpool_function_recyclejob\r
  87      * - @ref taskpool_function_schedule\r
  88      * - @ref taskpool_function_scheduledeferred\r
  89      * - @ref taskpool_function_getstatus\r
  90      * - @ref taskpool_function_trycancel\r
  91      *\r
  92      */\r
  93     IOT_TASKPOOL_BAD_PARAMETER,\r
  94 \r
  95     /**\r
  96      * @brief Task pool operation failed because it is illegal.\r
  97      *\r
  98      * Functions that may return this value:\r
  99      * - @ref taskpool_function_createjob\r
 100      * - @ref taskpool_function_createrecyclablejob\r
 101      * - @ref taskpool_function_destroyrecyclablejob\r
 102      * - @ref taskpool_function_recyclejob\r
 103      * - @ref taskpool_function_schedule\r
 104      * - @ref taskpool_function_scheduledeferred\r
 105      * - @ref taskpool_function_trycancel\r
 106      *\r
 107      */\r
 108     IOT_TASKPOOL_ILLEGAL_OPERATION,\r
 109 \r
 110     /**\r
 111      * @brief Task pool operation failed because allocating memory failed.\r
 112      *\r
 113      * Functions that may return this value:\r
 114      * - @ref taskpool_function_createsystemtaskpool\r
 115      * - @ref taskpool_function_create\r
 116      * - @ref taskpool_function_setmaxthreads\r
 117      * - @ref taskpool_function_createrecyclablejob\r
 118      * - @ref taskpool_function_scheduledeferred\r
 119      * - @ref taskpool_function_getstatus\r
 120      *\r
 121      */\r
 122     IOT_TASKPOOL_NO_MEMORY,\r
 123 \r
 124     /**\r
 125      * @brief Task pool operation failed because of an invalid parameter.\r
 126      *\r
 127      * Functions that may return this value:\r
 128      * - @ref taskpool_function_setmaxthreads\r
 129      * - @ref taskpool_function_createrecyclablejob\r
 130      * - @ref taskpool_function_destroyrecyclablejob\r
 131      * - @ref taskpool_function_recyclejob\r
 132      * - @ref taskpool_function_schedule\r
 133      * - @ref taskpool_function_scheduledeferred\r
 134      * - @ref taskpool_function_getstatus\r
 135      * - @ref taskpool_function_trycancel\r
 136      *\r
 137      */\r
 138     IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS,\r
 139 \r
 140     /**\r
 141      * @brief Task pool cancellation failed.\r
 142      *\r
 143      * Functions that may return this value:\r
 144      * - @ref taskpool_function_trycancel\r
 145      *\r
 146      */\r
 147     IOT_TASKPOOL_CANCEL_FAILED,\r
 148 } IotTaskPoolError_t;\r
 149 \r
 150 /**\r
 151  * @enums{taskpool,Task pool library}\r
 152  */\r
 153 \r
 154 /**\r
 155  * @ingroup taskpool_datatypes_enums\r
 156  * @brief Status codes of [task pool Job](@ref IotTaskPoolJob_t).\r
 157  *\r
 158  */\r
 159 typedef enum IotTaskPoolJobStatus\r
 160 {\r
 161     /**\r
 162      * @brief Job is ready to be scheduled.\r
 163      *\r
 164      */\r
 165     IOT_TASKPOOL_STATUS_READY = 0,\r
 166 \r
 167     /**\r
 168      * @brief Job has been queued for execution.\r
 169      *\r
 170      */\r
 171     IOT_TASKPOOL_STATUS_SCHEDULED,\r
 172 \r
 173     /**\r
 174      * @brief Job has been scheduled for deferred execution.\r
 175      *\r
 176      */\r
 177     IOT_TASKPOOL_STATUS_DEFERRED,\r
 178 \r
 179     /**\r
 180      * @brief Job is executing.\r
 181      *\r
 182      */\r
 183     IOT_TASKPOOL_STATUS_COMPLETED,\r
 184 \r
 185     /**\r
 186      * @brief Job has been canceled before executing.\r
 187      *\r
 188      */\r
 189     IOT_TASKPOOL_STATUS_CANCELED,\r
 190 \r
 191     /**\r
 192      * @brief Job status is undefined.\r
 193      *\r
 194      */\r
 195     IOT_TASKPOOL_STATUS_UNDEFINED,\r
 196 } IotTaskPoolJobStatus_t;\r
 197 \r
 198 /*------------------------- Task pool types and handles --------------------------*/\r
 199 \r
 200 /**\r
 201  * @ingroup taskpool_datatypes_handles\r
 202  * @brief Opaque handle of a Task Pool instance.\r
 203  *\r
 204  * This type identifies a Task Pool instance, which is valid after a successful call\r
 205  * to @ref taskpool_function_createsystemtaskpool or @ref taskpool_function_create. A\r
 206  *  variable of this type is passed as the first\r
 207  * argument to [Task Pool library functions](@ref taskpool_functions) to identify which\r
 208  * task pool that function acts on.\r
 209  *\r
 210  * A call to @ref taskpool_function_destroy makes a task pool handle invalid. Once\r
 211  * @ref taskpool_function_destroy returns, the task handle should no longer\r
 212  * be used.\r
 213  *\r
 214  * @initializer{IotTaskPool_t,IOT_TASKPOOL_INITIALIZER}\r
 215  */\r
 216 typedef struct _taskPool * IotTaskPool_t;\r
 217 \r
 218 /**\r
 219  * @ingroup taskpool_datatypes_structs\r
 220  * @brief The job storage data structure provides the storage for a statically allocated Task Pool Job instance.\r
 221  *\r
 222  * @warning This is a system-level data type that should not be modified or used directly in any application.\r
 223  * @warning This is a system-level data type that can and will change across different versions of the platform, with no regards for backward compatibility.\r
 224  *\r
 225  */\r
 226 typedef struct IotTaskPoolJobStorage\r
 227 {\r
 228     IotLink_t link;                 /**< @brief Placeholder. */\r
 229     void * dummy2;                  /**< @brief Placeholder. */\r
 230     void * dummy3;                  /**< @brief Placeholder. */\r
 231     uint32_t dummy4;                /**< @brief Placeholder. */\r
 232     IotTaskPoolJobStatus_t status;  /**< @brief Placeholder. */\r
 233 } IotTaskPoolJobStorage_t;\r
 234 \r
 235 /**\r
 236  * @ingroup taskpool_datatypes_handles\r
 237  * @brief Opaque handle of a Task Pool Job.\r
 238  *\r
 239  * This type identifies a Task Pool Job instance, which is valid after a successful call\r
 240  * to @ref taskpool_function_createjob or @ref taskpool_function_createrecyclablejob.\r
 241  *\r
 242  * A call to @ref taskpool_function_recyclejob or @ref taskpool_function_destroyrecyclablejob makes a\r
 243  * task pool job handle invalid. Once @ref taskpool_function_recyclejob or\r
 244  * @ref taskpool_function_destroyrecyclablejob returns, the task job handle should no longer be used.\r
 245  *\r
 246  * @initializer{IotTaskPoolJob_t,IOT_TASKPOOL_JOB_INITIALIZER}\r
 247  *\r
 248  */\r
 249 typedef struct _taskPoolJob * IotTaskPoolJob_t;\r
 250 \r
 251 /*------------------------- Task pool parameter structs --------------------------*/\r
 252 \r
 253 /**\r
 254  * @ingroup taskpool_datatypes_functionpointers\r
 255  * @brief Callback type for a user callback.\r
 256  *\r
 257  * This type identifies the user callback signature to execute a task pool job. This callback will be invoked\r
 258  * by the task pool threads with the `pUserContext` parameter, as specified by the user when\r
 259  * calling @ref IotTaskPool_Schedule.\r
 260  *\r
 261  */\r
 262 typedef void ( * IotTaskPoolRoutine_t )( IotTaskPool_t pTaskPool,\r
 263                                          IotTaskPoolJob_t pJob,\r
 264                                          void * pUserContext );\r
 265 \r
 266 /**\r
 267  * @ingroup taskpool_datatypes_paramstructs\r
 268  * @brief Initialization information to create one task pool instance.\r
 269  *\r
 270  * @paramfor  @ref taskpool_function_createsystemtaskpool @ref taskpool_function_create.\r
 271  *\r
 272  * Passed as an argument to @ref taskpool_function_create.\r
 273  *\r
 274  * @initializer{IotTaskPoolInfo_t,IOT_TASKPOOL_INFO_INITIALIZER}\r
 275  */\r
 276 typedef struct IotTaskPoolInfo\r
 277 {\r
 278     /**\r
 279      * @brief Specifies the operating parameters for a task pool.\r
 280      *\r
 281      * @attention #IotTaskPoolInfo_t.minThreads <b>MUST</b> be at least 1.\r
 282      * #IotTaskPoolInfo_t.maxThreads <b>MUST</b> be greater or equal to #IotTaskPoolInfo_t.minThreads.\r
 283      * If the minimum number of threads is same as the maximum, then the task pool will not try and grow the\r
 284      * number of worker threads at run time.\r
 285      */\r
 286 \r
 287     uint32_t minThreads; /**< @brief Minimum number of threads in a task pool. These threads will be created when the task pool is first created with @ref taskpool_function_create. */\r
 288     uint32_t maxThreads; /**< @brief Maximum number of threads in a task pool. A task pool may try and grow the number of active threads up to #IotTaskPoolInfo_t.maxThreads. */\r
 289     uint32_t stackSize;  /**< @brief Stack size for every task pool thread. The stack size for each thread is fixed after the task pool is created and cannot be changed. */\r
 290     int32_t priority;    /**< @brief priority for every task pool thread. The priority for each thread is fixed after the task pool is created and cannot be changed. */\r
 291 } IotTaskPoolInfo_t;\r
 292 \r
 293 /*------------------------- TASKPOOL defined constants --------------------------*/\r
 294 \r
 295 /**\r
 296  * @constantspage{taskpool,task pool library}\r
 297  *\r
 298  * @section taskpool_constants_initializers Task pool Initializers\r
 299  * @brief Provides default values for initializing the data types of the task pool library.\r
 300  *\r
 301  * @snippet this define_taskpool_initializers\r
 302  *\r
 303  * All user-facing data types of the task pool library can be initialized using\r
 304  * one of the following.\r
 305  *\r
 306  * @warning Failure to initialize a task pool data type with the appropriate initializer\r
 307  * may result in a runtime error!\r
 308  * @note The initializers may change at any time in future versions, but their\r
 309  * names will remain the same.\r
 310  *\r
 311  * <b>Example</b>\r
 312  * @code{c}\r
 313  *\r
 314  * IotTaskPool_t * pTaskPool;\r
 315  *\r
 316  * const IotTaskPoolInfo_t tpInfo = IOT_TASKPOOL_INFO_INITIALIZER_LARGE;\r
 317  *\r
 318  * IotTaskPoolError_t error = IotTaskPool_Create( &tpInfo, &pTaskPool );\r
 319  *\r
 320  * // Use the task pool\r
 321  * // ...\r
 322  *\r
 323  * @endcode\r
 324  *\r
 325  */\r
 326 /* @[define_taskpool_initializers] */\r
 327 /** @brief Initializer for a small #IotTaskPoolInfo_t. */\r
 328 #define IOT_TASKPOOL_INFO_INITIALIZER_SMALL     { .minThreads = 1, .maxThreads = 1, .stackSize = IOT_THREAD_DEFAULT_STACK_SIZE, .priority = IOT_THREAD_DEFAULT_PRIORITY }\r
 329 /** @brief Initializer for a medium #IotTaskPoolInfo_t. */\r
 330 #define IOT_TASKPOOL_INFO_INITIALIZER_MEDIUM    { .minThreads = 1, .maxThreads = 2, .stackSize = IOT_THREAD_DEFAULT_STACK_SIZE, .priority = IOT_THREAD_DEFAULT_PRIORITY }\r
 331 /** @brief Initializer for a large #IotTaskPoolInfo_t. */\r
 332 #define IOT_TASKPOOL_INFO_INITIALIZER_LARGE     { .minThreads = 2, .maxThreads = 3, .stackSize = IOT_THREAD_DEFAULT_STACK_SIZE, .priority = IOT_THREAD_DEFAULT_PRIORITY }\r
 333 /** @brief Initializer for a very large #IotTaskPoolInfo_t. */\r
 334 #define IOT_TASKPOOL_INFO_INITIALIZER_XLARGE    { .minThreads = 2, .maxThreads = 4, .stackSize = IOT_THREAD_DEFAULT_STACK_SIZE, .priority = IOT_THREAD_DEFAULT_PRIORITY }\r
 335 /** @brief Initializer for a typical #IotTaskPoolInfo_t. */\r
 336 #define IOT_TASKPOOL_INFO_INITIALIZER           IOT_TASKPOOL_INFO_INITIALIZER_MEDIUM\r
 337 /** @brief Initializer for a #IotTaskPool_t. */\r
 338 #define IOT_TASKPOOL_INITIALIZER                NULL\r
 339 /** @brief Initializer for a #IotTaskPoolJobStorage_t. */\r
 340 #define IOT_TASKPOOL_JOB_STORAGE_INITIALIZER    { { NULL, NULL }, NULL, NULL, 0, IOT_TASKPOOL_STATUS_UNDEFINED }\r
 341 /** @brief Initializer for a #IotTaskPoolJob_t. */\r
 342 #define IOT_TASKPOOL_JOB_INITIALIZER            NULL\r
 343 /* @[define_taskpool_initializers] */\r
 344 \r
 345 /**\r
 346  * @brief Flag for scheduling a job to execute immediately, even if the maximum number of threads in the\r
 347  * task pool was reached already.\r
 348  *\r
 349  * @warning This flag may cause the task pool to create a worker to serve the job immediately, and\r
 350  * therefore using this flag may incur in additional memory usage and potentially fail scheduling the job.\r
 351  */\r
 352 #define IOT_TASKPOOL_JOB_HIGH_PRIORITY    ( ( uint32_t ) 0x00000001 )\r
 353 \r
 354 /**\r
 355  * @brief Allows the use of the system task pool.\r
 356  *\r
 357  * @warning The system task pool handle is not valid unless @ref IotTaskPool_CreateSystemTaskPool is\r
 358  * called before the handle is used.\r
 359  */\r
 360 #define IOT_SYSTEM_TASKPOOL               ( NULL )\r
 361 \r
 362 #endif /* ifndef IOT_TASKPOOL_TYPES_H_ */\r