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