Task Pool API Reference
Task pool library
|
Implements the task pool functions in iot_taskpool.h. More...
#include "FreeRTOS.h"
#include "semphr.h"
#include "iot_config.h"
#include <stdbool.h>
#include <stdio.h>
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "private/iot_taskpool_internal.h"
Macros | |
#define | TASKPOOL_MAX_SEM_VALUE 0xFFFF |
Maximum semaphore value for wait operations. | |
#define | TASKPOOL_JOB_RESCHEDULE_DELAY_MS ( 10ULL ) |
Reschedule delay in milliseconds for deferred jobs. | |
Functions | |
static void | _initJobsCache (_taskPoolCache_t *const pCache) |
Initializes one instance of a Task pool cache. More... | |
static void | _initializeJob (_taskPoolJob_t *const pJob, IotTaskPoolRoutine_t userCallback, void *pUserContext, bool isStatic) |
Initialize a job. More... | |
static _taskPoolJob_t * | _fetchOrAllocateJob (_taskPoolCache_t *const pCache) |
Extracts and initializes one instance of a job from the cache or, if there is none available, it allocates and initialized a new one. More... | |
static void | _recycleJob (_taskPoolCache_t *const pCache, _taskPoolJob_t *const pJob) |
static void | _destroyJob (_taskPoolJob_t *const pJob) |
static void | _taskPoolWorker (void *pUserContext) |
static int32_t | _timerEventCompare (const IotLink_t *const pTimerEventLink1, const IotLink_t *const pTimerEventLink2) |
static void | _rescheduleDeferredJobsTimer (TimerHandle_t const timer, _taskPoolTimerEvent_t *const pFirstTimerEvent) |
static void | _timerCallback (TimerHandle_t xTimer) |
static IotTaskPoolError_t | _performTaskPoolParameterValidation (const IotTaskPoolInfo_t *const pInfo) |
static void | _initTaskPoolControlStructures (_taskPool_t *const pTaskPool) |
static IotTaskPoolError_t | _createTaskPool (const IotTaskPoolInfo_t *const pInfo, _taskPool_t *const pTaskPool) |
static void | _destroyTaskPool (_taskPool_t *const pTaskPool) |
static IotTaskPoolError_t | _scheduleInternal (_taskPool_t *const pTaskPool, _taskPoolJob_t *const pJob) |
static bool | _matchJobByPointer (const IotLink_t *const pLink, void *pMatch) |
static IotTaskPoolError_t | _tryCancelInternal (_taskPool_t *const pTaskPool, _taskPoolJob_t *const pJob, IotTaskPoolJobStatus_t *const pStatus) |
IotTaskPoolError_t | IotTaskPool_CreateSystemTaskPool (const IotTaskPoolInfo_t *const pInfo) |
Creates the one single instance of the system task pool. More... | |
IotTaskPoolError_t | IotTaskPool_CreateJob (IotTaskPoolRoutine_t userCallback, void *pUserContext, IotTaskPoolJobStorage_t *const pJobStorage, IotTaskPoolJob_t *const ppJob) |
Creates a job for the task pool around a user-provided storage. More... | |
IotTaskPoolError_t | IotTaskPool_CreateRecyclableJob (IotTaskPool_t taskPoolHandle, IotTaskPoolRoutine_t userCallback, void *pUserContext, IotTaskPoolJob_t *const ppJob) |
Creates a job for the task pool by allocating the job dynamically. More... | |
IotTaskPoolError_t | IotTaskPool_DestroyRecyclableJob (IotTaskPool_t taskPoolHandle, IotTaskPoolJob_t pJobHandle) |
This function un-initializes a job. More... | |
IotTaskPoolError_t | IotTaskPool_RecycleJob (IotTaskPool_t taskPoolHandle, IotTaskPoolJob_t pJob) |
Recycles a job into the task pool job cache. More... | |
IotTaskPoolError_t | IotTaskPool_Schedule (IotTaskPool_t taskPoolHandle, IotTaskPoolJob_t pJob, uint32_t flags) |
This function schedules a job created with IotTaskPool_CreateJob or IotTaskPool_CreateRecyclableJob against the task pool pointed to by taskPool . More... | |
IotTaskPoolError_t | IotTaskPool_ScheduleDeferred (IotTaskPool_t taskPoolHandle, IotTaskPoolJob_t job, uint32_t timeMs) |
This function schedules a job created with IotTaskPool_CreateJob against the task pool pointed to by taskPool to be executed after a user-defined time interval. More... | |
IotTaskPoolError_t | IotTaskPool_GetStatus (IotTaskPool_t taskPoolHandle, IotTaskPoolJob_t job, IotTaskPoolJobStatus_t *const pStatus) |
This function retrieves the current status of a job. More... | |
IotTaskPoolError_t | IotTaskPool_TryCancel (IotTaskPool_t taskPoolHandle, IotTaskPoolJob_t job, IotTaskPoolJobStatus_t *const pStatus) |
This function tries to cancel a job that was previously scheduled with IotTaskPool_Schedule. More... | |
IotTaskPoolJobStorage_t * | IotTaskPool_GetJobStorageFromHandle (IotTaskPoolJob_t pJob) |
Returns a pointer to the job storage from an instance of a job handle of type IotTaskPoolJob_t. This function is guaranteed to succeed for a valid job handle. More... | |
const char * | IotTaskPool_strerror (IotTaskPoolError_t status) |
Returns a string that describes an IotTaskPoolError_t. More... | |
Variables | |
static _taskPool_t | _IotSystemTaskPool = { .dispatchQueue = IOT_DEQUEUE_INITIALIZER } |
The system task pool handle for all libraries to use. User application can use the system task pool as well knowing that the usage will be shared with the system libraries as well. The system task pool needs to be initialized before any library is used or before any code that posts jobs to the task pool runs. More... | |
Implements the task pool functions in iot_taskpool.h.
|
static |
Initializes one instance of a Task pool cache.
[in] | pCache | The pre-allocated instance of the cache to initialize. |
|
static |
Initialize a job.
[in] | pJob | The job to initialize. |
[in] | userCallback | The user callback for the job. |
[in] | pUserContext | The context tp be passed to the callback. |
[in] | isStatic | A flag to indicate whether the job is statically or synamically allocated. |
|
static |
Extracts and initializes one instance of a job from the cache or, if there is none available, it allocates and initialized a new one.
[in] | pCache | The instance of the cache to extract the job from. |
|
static |
Recycles one instance of a job into the cache or, if the cache is full, it destroys it.
[in] | pCache | The instance of the cache to recycle the job into. |
[in] | pJob | The job to recycle. |
|
static |
Destroys one instance of a job.
[in] | pJob | The job to destroy. |
|
static |
The procedure for a task pool worker thread.
[in] | pUserContext | The user context. |
|
static |
Comparer for the time list.
param[in] pTimerEventLink1 The link to the first timer event. param[in] pTimerEventLink1 The link to the first timer event.
|
static |
Reschedules the timer for handling deferred jobs to the next timeout.
param[in] timer The timer to reschedule. param[in] pFirstTimerEvent The timer event that carries the timeout and job inforamtion.
|
static |
The task pool timer procedure for scheduling deferred jobs.
param[in] timer The timer to handle.
|
static |
Parameter validation for a task pool initialization.
[in] | pInfo | The initialization information for the task pool. |
|
static |
Initializes a pre-allocated instance of a task pool.
[in] | pTaskPool | The pre-allocated instance of the task pool to initialize. |
|
static |
Initializes a pre-allocated instance of a task pool.
[in] | pInfo | The initialization information for the task pool. |
[out] | pTaskPool | A pointer to the task pool data structure to initialize. |
|
static |
Destroys one instance of a task pool.
[in] | pTaskPool | The task pool to destroy. |
|
static |
Places a job in the dispatch queue.
[in] | pTaskPool | The task pool to scheduel the job with. |
[in] | pJob | The job to schedule. |
|
static |
Matches a deferred job in the timer queue with its timer event wrapper.
[in] | pLink | A pointer to the timer event link in the timer queue. |
[in] | pMatch | A pointer to the job to match. |
|
static |
Tries to cancel a job.
[in] | pTaskPool | The task pool to cancel an operation against. |
[in] | pJob | The job to cancel. |
[out] | pStatus | The status of the job at the time of cancellation. |
IotTaskPoolError_t IotTaskPool_CreateSystemTaskPool | ( | const IotTaskPoolInfo_t *const | pInfo | ) |
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 IotTaskPool_GetSystemTaskPool or the shortcut IOT_SYSTEM_TASKPOOL.
[in] | pInfo | A pointer to the task pool initialization data. |
IotTaskPoolError_t IotTaskPool_CreateJob | ( | IotTaskPoolRoutine_t | userCallback, |
void * | pUserContext, | ||
IotTaskPoolJobStorage_t *const | pJobStorage, | ||
IotTaskPoolJob_t *const | pJob | ||
) |
Creates a job for the task pool around a user-provided storage.
This function may allocate memory to hold the state for a job.
[in] | userCallback | A user-specified callback for the job. |
[in] | pUserContext | A user-specified context for the callback. |
[in] | pJobStorage | The storage for the job data structure. |
[out] | pJob | A pointer to an instance of IotTaskPoolJob_t that will be initialized when this function returns successfully. This handle can be used to inspect the job status with IotTaskPool_GetStatus or cancel the job with IotTaskPool_TryCancel, etc.... |
IotTaskPoolError_t IotTaskPool_CreateRecyclableJob | ( | IotTaskPool_t | taskPool, |
IotTaskPoolRoutine_t | userCallback, | ||
void * | pUserContext, | ||
IotTaskPoolJob_t *const | pJob | ||
) |
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 IotTaskPool_CreateRecyclableJob.
[in] | taskPool | A handle to the task pool for which to create a recyclable job. |
[in] | userCallback | A user-specified callback for the job. |
[in] | pUserContext | A user-specified context for the callback. |
[out] | pJob | A pointer to an instance of IotTaskPoolJob_t that will be initialized when this function returns successfully. This handle can be used to inspect the job status with IotTaskPool_GetStatus or cancel the job with IotTaskPool_TryCancel, etc.... |
IotTaskPoolError_t IotTaskPool_DestroyRecyclableJob | ( | IotTaskPool_t | taskPool, |
IotTaskPoolJob_t | job | ||
) |
This function un-initializes a job.
This function will destroy a job created with 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 IotTaskPool_TryCancel. An attempt to destroy a job that was scheduled but not yet executed or canceled, may result in a IOT_TASKPOOL_ILLEGAL_OPERATION error.
[in] | taskPool | A handle to the task pool, e.g. as returned by a call to IotTaskPool_Create or IotTaskPool_CreateSystemTaskPool. |
[in] | job | A handle to a job that was create with a call to IotTaskPool_CreateJob. |
IotTaskPoolError_t IotTaskPool_RecycleJob | ( | IotTaskPool_t | taskPool, |
IotTaskPoolJob_t | job | ||
) |
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 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 IOT_TASKPOOL_ILLEGAL_OPERATION error.
[in] | taskPool | A handle to the task pool, e.g. as returned by a call to IotTaskPool_Create. |
[out] | job | A pointer to a job that was create with a call to IotTaskPool_CreateJob. |
taskPool
used in this function should be the same used to create the job pointed to by job
, or the results will be undefined.IotTaskPoolError_t IotTaskPool_Schedule | ( | IotTaskPool_t | taskPool, |
IotTaskPoolJob_t | job, | ||
uint32_t | flags | ||
) |
This function schedules a job created with IotTaskPool_CreateJob or IotTaskPool_CreateRecyclableJob against the task pool pointed to by taskPool
.
See Design for a description of the jobs lifetime and interaction with the threads used in the task pool library.
[in] | taskPool | A handle to the task pool that must have been previously initialized with. a call to IotTaskPool_Create. |
[in] | job | A job to schedule for execution. This must be first initialized with a call to IotTaskPool_CreateJob. |
[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. |
taskPool
used in this function should be the same used to create the job pointed to by job
, or the results will be undefined.Example
IotTaskPoolError_t IotTaskPool_ScheduleDeferred | ( | IotTaskPool_t | taskPool, |
IotTaskPoolJob_t | job, | ||
uint32_t | timeMs | ||
) |
This function schedules a job created with IotTaskPool_CreateJob against the task pool pointed to by taskPool
to be executed after a user-defined time interval.
See Design for a description of the jobs lifetime and interaction with the threads used in the task pool library.
[in] | taskPool | A handle to the task pool that must have been previously initialized with. a call to IotTaskPool_Create. |
[in] | job | A job to schedule for execution. This must be first initialized with a call to IotTaskPool_CreateJob. |
[in] | timeMs | The time in milliseconds to wait before scheduling the job. |
taskPool
used in this function should be the same used to create the job pointed to by job
, or the results will be undefined. IotTaskPoolError_t IotTaskPool_GetStatus | ( | IotTaskPool_t | taskPool, |
IotTaskPoolJob_t | job, | ||
IotTaskPoolJobStatus_t *const | pStatus | ||
) |
This function retrieves the current status of a job.
[in] | taskPool | A handle to the task pool that must have been previously initialized with a call to IotTaskPool_Create or IotTaskPool_CreateSystemTaskPool. |
[in] | job | The job to cancel. |
[out] | pStatus | The status of the job at the time of cancellation. |
pStatus
may be invalid by the time the calling thread has a chance to inspect it. IotTaskPoolError_t IotTaskPool_TryCancel | ( | IotTaskPool_t | taskPool, |
IotTaskPoolJob_t | job, | ||
IotTaskPoolJobStatus_t *const | pStatus | ||
) |
This function tries to cancel a job that was previously scheduled with IotTaskPool_Schedule.
A job can be canceled only if it is not yet executing, i.e. if its status is IOT_TASKPOOL_STATUS_READY or IOT_TASKPOOL_STATUS_SCHEDULED. Calling IotTaskPool_TryCancel on a job whose status is IOT_TASKPOOL_STATUS_COMPLETED, or IOT_TASKPOOL_STATUS_CANCELED will yield a IOT_TASKPOOL_CANCEL_FAILED return result.
[in] | taskPool | A handle to the task pool that must have been previously initialized with a call to IotTaskPool_Create. |
[in] | job | The job to cancel. |
[out] | pStatus | The status of the job at the time of cancellation. |
taskPool
used in this function should be the same used to create the job pointed to by job
, or the results will be undefined. IotTaskPoolJobStorage_t* IotTaskPool_GetJobStorageFromHandle | ( | IotTaskPoolJob_t | job | ) |
Returns a pointer to the job storage from an instance of a job handle of type IotTaskPoolJob_t. This function is guaranteed to succeed for a valid job handle.
[in] | job | The job handle. |
job
.job
handle used is invalid, the results will be undefined. const char* IotTaskPool_strerror | ( | IotTaskPoolError_t | status | ) |
Returns a string that describes an 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 MUST 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.
[in] | status | The status to describe. |
status
.
|
static |
The system task pool handle for all libraries to use. User application can use the system task pool as well knowing that the usage will be shared with the system libraries as well. The system task pool needs to be initialized before any library is used or before any code that posts jobs to the task pool runs.
Doxygen should ignore this section.