+++ /dev/null
-/*\r
- * Amazon FreeRTOS Common V1.0.0\r
- * Copyright (C) 2018 Amazon.com, Inc. or its affiliates. All Rights Reserved.\r
- *\r
- * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
- * this software and associated documentation files (the "Software"), to deal in\r
- * the Software without restriction, including without limitation the rights to\r
- * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
- * the Software, and to permit persons to whom the Software is furnished to do so,\r
- * subject to the following conditions:\r
- *\r
- * The above copyright notice and this permission notice shall be included in all\r
- * copies or substantial portions of the Software.\r
- *\r
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
- * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
- * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
- * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
- * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
- *\r
- * http://aws.amazon.com/freertos\r
- * http://www.FreeRTOS.org\r
- */\r
-\r
-/**\r
- * @file iot_taskpool.h\r
- * @brief User-facing functions of the task pool library.\r
- */\r
-\r
-#ifndef IOT_TASKPOOL_H_\r
-#define IOT_TASKPOOL_H_\r
-\r
-/* The config header is always included first. */\r
-#include "iot_config.h"\r
-\r
-/* Standard includes. */\r
-#include <stdbool.h>\r
-#include <stdint.h>\r
-#include <stddef.h>\r
-\r
-/* Task pool types. */\r
-#include "types/iot_taskpool_types.h"\r
-\r
-/*------------------------- Task Pool library functions --------------------------*/\r
-\r
-/**\r
- * @functionspage{taskpool,task pool library}\r
- * - @functionname{taskpool_function_createsystemtaskpool}\r
- * - @functionname{taskpool_function_getsystemtaskpool}\r
- * - @functionname{taskpool_function_create}\r
- * - @functionname{taskpool_function_destroy}\r
- * - @functionname{taskpool_function_setmaxthreads}\r
- * - @functionname{taskpool_function_createjob}\r
- * - @functionname{taskpool_function_createrecyclablejob}\r
- * - @functionname{taskpool_function_destroyrecyclablejob}\r
- * - @functionname{taskpool_function_recyclejob}\r
- * - @functionname{taskpool_function_schedule}\r
- * - @functionname{taskpool_function_scheduledeferred}\r
- * - @functionname{taskpool_function_getstatus}\r
- * - @functionname{taskpool_function_trycancel}\r
- * - @functionname{taskpool_function_getjobstoragefromhandle}\r
- * - @functionname{taskpool_function_strerror}\r
- */\r
-\r
-/**\r
- * @functionpage{IotTaskPool_CreateSystemTaskPool,taskpool,createsystemtaskpool}\r
- * @functionpage{IotTaskPool_GetSystemTaskPool,taskpool,getsystemtaskpool}\r
- * @functionpage{IotTaskPool_Create,taskpool,create}\r
- * @functionpage{IotTaskPool_Destroy,taskpool,destroy}\r
- * @functionpage{IotTaskPool_SetMaxThreads,taskpool,setmaxthreads}\r
- * @functionpage{IotTaskPool_CreateJob,taskpool,createjob}\r
- * @functionpage{IotTaskPool_CreateRecyclableJob,taskpool,createrecyclablejob}\r
- * @functionpage{IotTaskPool_DestroyRecyclableJob,taskpool,destroyrecyclablejob}\r
- * @functionpage{IotTaskPool_RecycleJob,taskpool,recyclejob}\r
- * @functionpage{IotTaskPool_Schedule,taskpool,schedule}\r
- * @functionpage{IotTaskPool_ScheduleDeferred,taskpool,scheduledeferred}\r
- * @functionpage{IotTaskPool_GetStatus,taskpool,getstatus}\r
- * @functionpage{IotTaskPool_TryCancel,taskpool,trycancel}\r
- * @functionpage{IotTaskPool_GetJobStorageFromHandle,taskpool,getjobstoragefromhandle}\r
- * @functionpage{IotTaskPool_strerror,taskpool,strerror}\r
- */\r
-\r
-/**\r
- * @brief Creates the one single instance of the system task pool.\r
- *\r
- * This function should be called once by the application to initialize the one single instance of the system task pool.\r
- * An application should initialize the system task pool early in the boot sequence, before initializing any other library\r
- * and before posting any jobs. Early initialization it typically easy to accomplish by creating the system task pool\r
- * before starting the scheduler.\r
- *\r
- * This function does not allocate memory to hold the task pool data structures and state, but it\r
- * may allocate memory to hold the dependent entities and data structures, e.g. the threads of the task\r
- * pool. The system task pool handle is recoverable for later use by calling @ref IotTaskPool_GetSystemTaskPool or\r
- * the shortcut @ref IOT_SYSTEM_TASKPOOL.\r
- *\r
- * @param[in] pInfo A pointer to the task pool initialization data.\r
- *\r
- * @return One of the following:\r
- * - #IOT_TASKPOOL_SUCCESS\r
- * - #IOT_TASKPOOL_BAD_PARAMETER\r
- * - #IOT_TASKPOOL_NO_MEMORY\r
- *\r
- * @warning This function should be called only once. Calling this function more that once will result in\r
- * undefined behavior.\r
- *\r
- */\r
-/* @[declare_taskpool_createsystemtaskpool] */\r
-IotTaskPoolError_t IotTaskPool_CreateSystemTaskPool( const IotTaskPoolInfo_t * const pInfo );\r
-/* @[declare_taskpool_createsystemtaskpool] */\r
-\r
-/**\r
- * @brief Retrieves the one and only instance of a system task pool\r
- *\r
- * This function retrieves the system task pool created with @ref IotTaskPool_CreateSystemTaskPool, and it is functionally\r
- * equivalent to using the shortcut @ref IOT_SYSTEM_TASKPOOL.\r
- *\r
- * @return The system task pool handle.\r
- *\r
- * @warning This function should be called after creating the system task pool with @ref IotTaskPool_CreateSystemTaskPool.\r
- * Calling this function before creating the system task pool may return a pointer to an uninitialized task pool, NULL, or otherwise\r
- * fail with undefined behaviour.\r
- *\r
- */\r
-/* @[declare_taskpool_getsystemtaskpool] */\r
-IotTaskPool_t IotTaskPool_GetSystemTaskPool( void );\r
-/* @[declare_taskpool_getsystemtaskpool] */\r
-\r
-/**\r
- * @brief Creates one instance of a task pool.\r
- *\r
- * This function should be called by the user to initialize one instance of a task\r
- * pool. The task pool instance will be created around the storage pointed to by the `pTaskPool`\r
- * parameter. This function will create the minimum number of threads requested by the user\r
- * through an instance of the #IotTaskPoolInfo_t type specified with the `pInfo` parameter.\r
- * This function does not allocate memory to hold the task pool data structures and state, but it\r
- * may allocates memory to hold the dependent data structures, e.g. the threads of the task\r
- * pool.\r
- *\r
- * @param[in] pInfo A pointer to the task pool initialization data.\r
- * @param[out] pTaskPool A pointer to the task pool handle to be used after initialization.\r
- * The pointer `pTaskPool` will hold a valid handle only if (@ref IotTaskPool_Create)\r
- * completes successfully.\r
- *\r
- * @return One of the following:\r
- * - #IOT_TASKPOOL_SUCCESS\r
- * - #IOT_TASKPOOL_BAD_PARAMETER\r
- * - #IOT_TASKPOOL_NO_MEMORY\r
- *\r
- */\r
-/* @[declare_taskpool_create] */\r
-IotTaskPoolError_t IotTaskPool_Create( const IotTaskPoolInfo_t * const pInfo,\r
- IotTaskPool_t * const pTaskPool );\r
-/* @[declare_taskpool_create] */\r
-\r
-/**\r
- * @brief Destroys a task pool instance and collects all memory associated with a task pool and its\r
- * satellite data structures.\r
- *\r
- * This function should be called to destroy one instance of a task pool previously created with a call\r
- * to @ref IotTaskPool_Create or @ref IotTaskPool_CreateSystemTaskPool.\r
- * Calling this fuction release all underlying resources. After calling this function, any job scheduled but not yet executed\r
- * will be canceled and destroyed.\r
- * The `taskPool` instance will no longer be valid after this function returns.\r
- *\r
- * @param[in] taskPool A handle to the task pool, e.g. as returned by a call to @ref IotTaskPool_Create or\r
- * @ref IotTaskPool_CreateSystemTaskPool. The `taskPool` instance will no longer be valid after this function returns.\r
- *\r
- * @return One of the following:\r
- * - #IOT_TASKPOOL_SUCCESS\r
- * - #IOT_TASKPOOL_BAD_PARAMETER\r
- *\r
- */\r
-/* @[declare_taskpool_destroy] */\r
-IotTaskPoolError_t IotTaskPool_Destroy( IotTaskPool_t taskPool );\r
-/* @[declare_taskpool_destroy] */\r
-\r
-/**\r
- * @brief Sets the maximum number of threads for one instance of a task pool.\r
- *\r
- * This function sets the maximum number of threads for the task pool\r
- * pointed to by `taskPool`.\r
- *\r
- * If the number of currently active threads in the task pool is greater than `maxThreads`, this\r
- * function causes the task pool to shrink the number of active threads.\r
- *\r
- * @param[in] taskPool A handle to the task pool that must have been previously initialized with\r
- * a call to @ref IotTaskPool_Create or @ref IotTaskPool_CreateSystemTaskPool.\r
- * @param[in] maxThreads The maximum number of threads for the task pool.\r
- *\r
- * @return One of the following:\r
- * - #IOT_TASKPOOL_SUCCESS\r
- * - #IOT_TASKPOOL_BAD_PARAMETER\r
- * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS\r
- *\r
- */\r
-/* @[declare_taskpool_setmaxthreads] */\r
-IotTaskPoolError_t IotTaskPool_SetMaxThreads( IotTaskPool_t taskPool,\r
- uint32_t maxThreads );\r
-/* @[declare_taskpool_setmaxthreads] */\r
-\r
-/**\r
- * @brief Creates a job for the task pool around a user-provided storage.\r
- *\r
- * This function may allocate memory to hold the state for a job.\r
- *\r
- * @param[in] userCallback A user-specified callback for the job.\r
- * @param[in] pUserContext A user-specified context for the callback.\r
- * @param[in] pJobStorage The storage for the job data structure.\r
- * @param[out] pJob A pointer to an instance of @ref IotTaskPoolJob_t that will be initialized when this\r
- * function returns successfully. This handle can be used to inspect the job status with\r
- * @ref IotTaskPool_GetStatus or cancel the job with @ref IotTaskPool_TryCancel, etc....\r
- *\r
- * @return One of the following:\r
- * - #IOT_TASKPOOL_SUCCESS\r
- * - #IOT_TASKPOOL_BAD_PARAMETER\r
- *\r
- *\r
- */\r
-/* @[declare_taskpool_createjob] */\r
-IotTaskPoolError_t IotTaskPool_CreateJob( IotTaskPoolRoutine_t userCallback,\r
- void * pUserContext,\r
- IotTaskPoolJobStorage_t * const pJobStorage,\r
- IotTaskPoolJob_t * const pJob );\r
-/* @[declare_taskpool_createjob] */\r
-\r
-/**\r
- * brief Creates a job for the task pool by allocating the job dynamically.\r
- *\r
- * A recyclable job does not need to be allocated twice, but it can rather be reused through\r
- * subsequent calls to @ref IotTaskPool_CreateRecyclableJob.\r
- *\r
- * @param[in] taskPool A handle to the task pool for which to create a recyclable job.\r
- * @param[in] userCallback A user-specified callback for the job.\r
- * @param[in] pUserContext A user-specified context for the callback.\r
- * @param[out] pJob A pointer to an instance of @ref IotTaskPoolJob_t that will be initialized when this\r
- * function returns successfully. This handle can be used to inspect the job status with\r
- * @ref IotTaskPool_GetStatus or cancel the job with @ref IotTaskPool_TryCancel, etc....\r
- *\r
- * @return One of the following:\r
- * - #IOT_TASKPOOL_SUCCESS\r
- * - #IOT_TASKPOOL_BAD_PARAMETER\r
- * - #IOT_TASKPOOL_NO_MEMORY\r
- * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS\r
- *\r
- * @note This function will not allocate memory. //_RB_ Incorrect comment.\r
- *\r
- * @warning A recyclable job should be recycled with a call to @ref IotTaskPool_RecycleJob rather than destroyed.\r
- *\r
- */\r
-/* @[declare_taskpool_createrecyclablejob] */\r
-IotTaskPoolError_t IotTaskPool_CreateRecyclableJob( IotTaskPool_t taskPool,\r
- IotTaskPoolRoutine_t userCallback,\r
- void * pUserContext,\r
- IotTaskPoolJob_t * const pJob );\r
-/* @[declare_taskpool_createrecyclablejob] */\r
-\r
-/**\r
- * @brief This function un-initializes a job.\r
- *\r
- * This function will destroy a job created with @ref IotTaskPool_CreateRecyclableJob.\r
- * A job should not be destroyed twice. A job that was previously scheduled but has not completed yet should not be destroyed,\r
- * but rather the application should attempt to cancel it first by calling @ref IotTaskPool_TryCancel.\r
- * An attempt to destroy a job that was scheduled but not yet executed or canceled, may result in a\r
- * @ref IOT_TASKPOOL_ILLEGAL_OPERATION error.\r
- *\r
- * @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
- * @param[in] job A handle to a job that was create with a call to @ref IotTaskPool_CreateJob.\r
- *\r
- * @return One of the following:\r
- * - #IOT_TASKPOOL_SUCCESS\r
- * - #IOT_TASKPOOL_BAD_PARAMETER\r
- * - #IOT_TASKPOOL_ILLEGAL_OPERATION\r
- * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS\r
- *\r
- * @warning The task pool will try and prevent destroying jobs that are currently queued for execution, but does\r
- * not enforce strict ordering of operations. It is up to the user to make sure @ref IotTaskPool_DestroyRecyclableJob is not called\r
- * our of order.\r
- *\r
- * @warning Calling this function on job that was not previously created with @ref IotTaskPool_CreateRecyclableJob\r
- * will result in a @ref IOT_TASKPOOL_ILLEGAL_OPERATION error.\r
- *\r
- */\r
-/* @[declare_taskpool_destroyrecyclablejob] */\r
-IotTaskPoolError_t IotTaskPool_DestroyRecyclableJob( IotTaskPool_t taskPool,\r
- IotTaskPoolJob_t job );\r
-/* @[declare_taskpool_destroyrecyclablejob] */\r
-\r
-/**\r
- * @brief Recycles a job into the task pool job cache.\r
- *\r
- * This function will try and recycle the job into the task pool cache. If the cache is full,\r
- * the job memory is destroyed as if the user called @ref IotTaskPool_DestroyRecyclableJob. The job should be recycled into\r
- * the task pool instance from where it was allocated.\r
- * Failure to do so will yield undefined results. A job should not be recycled twice. A job\r
- * that was previously scheduled but not completed or canceled cannot be safely recycled. An attempt to do so will result\r
- * in an @ref IOT_TASKPOOL_ILLEGAL_OPERATION error.\r
- *\r
- * @param[in] taskPool A handle to the task pool, e.g. as returned by a call to @ref IotTaskPool_Create.\r
- * @param[out] job A pointer to a job that was create with a call to @ref IotTaskPool_CreateJob.\r
- *\r
- * @return One of the following:\r
- * - #IOT_TASKPOOL_SUCCESS\r
- * - #IOT_TASKPOOL_BAD_PARAMETER\r
- * - #IOT_TASKPOOL_ILLEGAL_OPERATION\r
- * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS\r
- *\r
- * @warning The `taskPool` used in this function should be the same\r
- * used to create the job pointed to by `job`, or the results will be undefined.\r
- *\r
- * @warning Attempting to call this function on a statically allocated job will result in @ref IOT_TASKPOOL_ILLEGAL_OPERATION\r
- * error.\r
- *\r
- * @warning This function should be used to recycle a job in the task pool cache when after the job executed.\r
- * Failing to call either this function or @ref IotTaskPool_DestroyRecyclableJob will result is a memory leak. Statically\r
- * allocated jobs do not need to be recycled or destroyed.\r
- *\r
- */\r
-/* @[declare_taskpool_recyclejob] */\r
-IotTaskPoolError_t IotTaskPool_RecycleJob( IotTaskPool_t taskPool,\r
- IotTaskPoolJob_t job );\r
-/* @[declare_taskpool_recyclejob] */\r
-\r
-/**\r
- * @brief This function schedules a job created with @ref IotTaskPool_CreateJob or @ref IotTaskPool_CreateRecyclableJob\r
- * against the task pool pointed to by `taskPool`.\r
- *\r
- * See @ref taskpool_design for a description of the jobs lifetime and interaction with the threads used in the task pool\r
- * library.\r
- *\r
- * @param[in] taskPool A handle to the task pool that must have been previously initialized with.\r
- * a call to @ref IotTaskPool_Create.\r
- * @param[in] job A job to schedule for execution. This must be first initialized with a call to @ref IotTaskPool_CreateJob.\r
- * @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
- *\r
- * @return One of the following:\r
- * - #IOT_TASKPOOL_SUCCESS\r
- * - #IOT_TASKPOOL_BAD_PARAMETER\r
- * - #IOT_TASKPOOL_ILLEGAL_OPERATION\r
- * - #IOT_TASKPOOL_NO_MEMORY\r
- * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS\r
- *\r
- *\r
- * @note This function will not allocate memory, so it is guaranteed to succeed if the paramters are correct and the task pool\r
- * was correctly initialized, and not yet destroyed.\r
- *\r
- * @warning The `taskPool` used in this function should be the same used to create the job pointed to by `job`, or the\r
- * results will be undefined.\r
- *\r
- * <b>Example</b>\r
- * @code{c}\r
- * // An example of a user context to pass to a callback through a task pool thread.\r
- * typedef struct JobUserContext\r
- * {\r
- * uint32_t counter;\r
- * } JobUserContext_t;\r
- *\r
- * // An example of a user callback to invoke through a task pool thread.\r
- * static void ExecutionCb( IotTaskPool_t taskPool, IotTaskPoolJob_t job, void * context )\r
- * {\r
- * ( void )taskPool;\r
- * ( void )job;\r
- *\r
- * JobUserContext_t * pUserContext = ( JobUserContext_t * )context;\r
- *\r
- * pUserContext->counter++;\r
- * }\r
- *\r
- * void TaskPoolExample( )\r
- * {\r
- * JobUserContext_t userContext = { 0 };\r
- * IotTaskPoolJob_t job;\r
- * IotTaskPool_t taskPool;\r
- *\r
- * // Configure the task pool to hold at least two threads and three at the maximum.\r
- * // Provide proper stack size and priority per the application needs.\r
- *\r
- * const IotTaskPoolInfo_t tpInfo = { .minThreads = 2, .maxThreads = 3, .stackSize = 512, .priority = 0 };\r
- *\r
- * // Create a task pool.\r
- * IotTaskPool_Create( &tpInfo, &taskPool );\r
- *\r
- * // Statically allocate one job, schedule it.\r
- * IotTaskPool_CreateJob( &ExecutionCb, &userContext, &job );\r
- *\r
- * IotTaskPoolError_t errorSchedule = IotTaskPool_Schedule( taskPool, &job, 0 );\r
- *\r
- * switch ( errorSchedule )\r
- * {\r
- * case IOT_TASKPOOL_SUCCESS:\r
- * break;\r
- * case IOT_TASKPOOL_BAD_PARAMETER: // Invalid parameters, such as a NULL handle, can trigger this error.\r
- * case IOT_TASKPOOL_ILLEGAL_OPERATION: // Scheduling a job that was previously scheduled or destroyed could trigger this error.\r
- * case IOT_TASKPOOL_NO_MEMORY: // Scheduling a with flag #IOT_TASKPOOL_JOB_HIGH_PRIORITY could trigger this error.\r
- * case IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS: // Scheduling a job after trying to destroy the task pool could trigger this error.\r
- * // ASSERT\r
- * break;\r
- * default:\r
- * // ASSERT\r
- * }\r
- *\r
- * //\r
- * // ... Perform other operations ...\r
- * //\r
- *\r
- * IotTaskPool_Destroy( taskPool );\r
- * }\r
- * @endcode\r
- */\r
-/* @[declare_taskpool_schedule] */\r
-IotTaskPoolError_t IotTaskPool_Schedule( IotTaskPool_t taskPool,\r
- IotTaskPoolJob_t job,\r
- uint32_t flags );\r
-/* @[declare_taskpool_schedule] */\r
-\r
-/**\r
- * @brief This function schedules a job created with @ref IotTaskPool_CreateJob against the task pool\r
- * pointed to by `taskPool` to be executed after a user-defined time interval.\r
- *\r
- * See @ref taskpool_design for a description of the jobs lifetime and interaction with the threads used in the task pool\r
- * library.\r
- *\r
- * @param[in] taskPool A handle to the task pool that must have been previously initialized with.\r
- * a call to @ref IotTaskPool_Create.\r
- * @param[in] job A job to schedule for execution. This must be first initialized with a call to @ref IotTaskPool_CreateJob.\r
- * @param[in] timeMs The time in milliseconds to wait before scheduling the job.\r
- *\r
- * @return One of the following:\r
- * - #IOT_TASKPOOL_SUCCESS\r
- * - #IOT_TASKPOOL_BAD_PARAMETER\r
- * - #IOT_TASKPOOL_ILLEGAL_OPERATION\r
- * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS\r
- *\r
- *\r
- * @note This function will not allocate memory.\r
- *\r
- * @warning The `taskPool` used in this function should be the same\r
- * used to create the job pointed to by `job`, or the results will be undefined.\r
- *\r
- */\r
-/* @[declare_taskpool_scheduledeferred] */\r
-IotTaskPoolError_t IotTaskPool_ScheduleDeferred( IotTaskPool_t taskPool,\r
- IotTaskPoolJob_t job,\r
- uint32_t timeMs );\r
-/* @[declare_taskpool_scheduledeferred] */\r
-\r
-/**\r
- * @brief This function retrieves the current status of a job.\r
- *\r
- * @param[in] taskPool A handle to the task pool that must have been previously initialized with\r
- * a call to @ref IotTaskPool_Create or @ref IotTaskPool_CreateSystemTaskPool.\r
- * @param[in] job The job to cancel.\r
- * @param[out] pStatus The status of the job at the time of cancellation.\r
- *\r
- * @return One of the following:\r
- * - #IOT_TASKPOOL_SUCCESS\r
- * - #IOT_TASKPOOL_BAD_PARAMETER\r
- * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS\r
- *\r
- * @warning This function is not thread safe and the job status returned in `pStatus` may be invalid by the time\r
- * the calling thread has a chance to inspect it.\r
- */\r
-/* @[declare_taskpool_getstatus] */\r
-IotTaskPoolError_t IotTaskPool_GetStatus( IotTaskPool_t taskPool,\r
- IotTaskPoolJob_t job,\r
- IotTaskPoolJobStatus_t * const pStatus );\r
-/* @[declare_taskpool_getstatus] */\r
-\r
-/**\r
- * @brief This function tries to cancel a job that was previously scheduled with @ref IotTaskPool_Schedule.\r
- *\r
- * A job can be canceled only if it is not yet executing, i.e. if its status is\r
- * @ref IOT_TASKPOOL_STATUS_READY or @ref IOT_TASKPOOL_STATUS_SCHEDULED. Calling\r
- * @ref IotTaskPool_TryCancel on a job whose status is @ref IOT_TASKPOOL_STATUS_COMPLETED,\r
- * or #IOT_TASKPOOL_STATUS_CANCELED will yield a #IOT_TASKPOOL_CANCEL_FAILED return result.\r
- *\r
- * @param[in] taskPool A handle to the task pool that must have been previously initialized with\r
- * a call to @ref IotTaskPool_Create.\r
- * @param[in] job The job to cancel.\r
- * @param[out] pStatus The status of the job at the time of cancellation.\r
- *\r
- * @return One of the following:\r
- * - #IOT_TASKPOOL_SUCCESS\r
- * - #IOT_TASKPOOL_BAD_PARAMETER\r
- * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS\r
- * - #IOT_TASKPOOL_CANCEL_FAILED\r
- *\r
- * @warning The `taskPool` used in this function should be the same\r
- * used to create the job pointed to by `job`, or the results will be undefined.\r
- *\r
- */\r
-/* @[declare_taskpool_trycancel] */\r
-IotTaskPoolError_t IotTaskPool_TryCancel( IotTaskPool_t taskPool,\r
- IotTaskPoolJob_t job,\r
- IotTaskPoolJobStatus_t * const pStatus );\r
-/* @[declare_taskpool_trycancel] */\r
-\r
-/**\r
- * @brief Returns a pointer to the job storage from an instance of a job handle\r
- * of type @ref IotTaskPoolJob_t. This function is guaranteed to succeed for a\r
- * valid job handle.\r
- *\r
- * @param[in] job The job handle.\r
- *\r
- * @return A pointer to the storage associated with the job handle `job`.\r
- *\r
- * @warning If the `job` handle used is invalid, the results will be undefined.\r
- */\r
-/* @[declare_taskpool_getjobstoragefromhandle] */\r
-IotTaskPoolJobStorage_t * IotTaskPool_GetJobStorageFromHandle( IotTaskPoolJob_t job );\r
-/* @[declare_taskpool_getjobstoragefromhandle] */\r
-\r
-/**\r
- * @brief Returns a string that describes an @ref IotTaskPoolError_t.\r
- *\r
- * Like the POSIX's `strerror`, this function returns a string describing a\r
- * return code. In this case, the return code is a task pool library error code,\r
- * `status`.\r
- *\r
- * The string returned by this function <b>MUST</b> be treated as read-only: any\r
- * attempt to modify its contents may result in a crash. Therefore, this function\r
- * is limited to usage in logging.\r
- *\r
- * @param[in] status The status to describe.\r
- *\r
- * @return A read-only string that describes `status`.\r
- *\r
- * @warning The string returned by this function must never be modified.\r
- */\r
-/* @[declare_taskpool_strerror] */\r
-const char * IotTaskPool_strerror( IotTaskPoolError_t status );\r
-/* @[declare_taskpool_strerror] */\r
-\r
-/**\r
- * @brief The maximum number of task pools to be created when using\r
- * a memory pool.\r
- */\r
-#ifndef IOT_TASKPOOLS\r
-#define IOT_TASKPOOLS ( 4 )\r
-#endif\r
-\r
-/**\r
- * @brief The maximum number of jobs to cache.\r
- */\r
-#ifndef IOT_TASKPOOL_JOBS_RECYCLE_LIMIT\r
- #define IOT_TASKPOOL_JOBS_RECYCLE_LIMIT ( 8UL )\r
-#endif\r
-\r
-/**\r
- * @brief The maximum timeout in milliseconds to wait for a job to be scheduled before waking up a worker thread.\r
- * 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
- * minimum number of threads.\r
- */\r
-#ifndef IOT_TASKPOOL_JOB_WAIT_TIMEOUT_MS\r
- #define IOT_TASKPOOL_JOB_WAIT_TIMEOUT_MS ( 60 * 1000UL )\r
-#endif\r
-\r
-#endif /* ifndef IOT_TASKPOOL_H_ */\r
projects / freertos / blobdiff