User-facing functions of the task pool library. More...

#include "iot_config.h"
#include <stdbool.h>
#include <stdint.h>
#include <stddef.h>
#include "types/iot_taskpool_types.h"

Macros
#define	IOT_TASKPOOLS ( 4 )
	The maximum number of task pools to be created when using a memory pool.

#define	IOT_TASKPOOL_JOBS_RECYCLE_LIMIT ( 8UL )
	The maximum number of jobs to cache.

#define	IOT_TASKPOOL_JOB_WAIT_TIMEOUT_MS ( 60 * 1000UL )
	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.

Functions
IotTaskPoolError_t	IotTaskPool_CreateSystemTaskPool (const IotTaskPoolInfo_t *pInfo)
	Creates the one single instance of the system task pool. More...

IotTaskPool_t	IotTaskPool_GetSystemTaskPool (void)
	Retrieves the one and only instance of a system task pool. More...

IotTaskPoolError_t	IotTaskPool_Create (const IotTaskPoolInfo_t pInfo, IotTaskPool_t const pTaskPool)
	Creates one instance of a task pool. More...

IotTaskPoolError_t	IotTaskPool_Destroy (IotTaskPool_t taskPool)
	Destroys a task pool instance and collects all memory associated with a task pool and its satellite data structures. More...

IotTaskPoolError_t	IotTaskPool_SetMaxThreads (IotTaskPool_t taskPool, uint32_t maxThreads)
	Sets the maximum number of threads for one instance of a task pool. More...

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. More...

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. More...

IotTaskPoolError_t	IotTaskPool_DestroyRecyclableJob (IotTaskPool_t taskPool, IotTaskPoolJob_t job)
	This function un-initializes a job. More...

IotTaskPoolError_t	IotTaskPool_RecycleJob (IotTaskPool_t taskPool, IotTaskPoolJob_t job)
	Recycles a job into the task pool job cache. More...

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`. More...

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. More...

IotTaskPoolError_t	IotTaskPool_GetStatus (IotTaskPool_t taskPool, IotTaskPoolJob_t job, IotTaskPoolJobStatus_t *const pStatus)
	This function retrieves the current status of a job. More...

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. More...

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. More...

const char *	IotTaskPool_strerror (IotTaskPoolError_t status)
	Returns a string that describes an IotTaskPoolError_t. More...

Detailed Description

User-facing functions of the task pool library.

Function Documentation

◆ IotTaskPool_CreateSystemTaskPool()

IotTaskPoolError_t IotTaskPool_CreateSystemTaskPool ( const IotTaskPoolInfo_t * 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 that uses the system task pool, such as MQTT, Shadow, Defender, etc. An application should also initialize the system task pool before posting any jobs. Early initialization is typically easy to accomplish by creating the system task pool before the scheduler is started.

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.

Parameters

[in] pInfo A pointer to the task pool initialization data.

Returns

One of the following:

Warning: This function should be called only once. Calling this function more that once will result in undefined behavior.

◆ IotTaskPool_GetSystemTaskPool()

IotTaskPool_t IotTaskPool_GetSystemTaskPool ( void )

Retrieves the one and only instance of a system task pool.

This function retrieves the system task pool created with IotTaskPool_CreateSystemTaskPool, and it is functionally equivalent to using the shortcut IOT_SYSTEM_TASKPOOL.

Returns: The system task pool handle.

Warning: This function should be called after creating the system task pool with 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.

◆ IotTaskPool_Create()

IotTaskPoolError_t IotTaskPool_Create	(	const IotTaskPoolInfo_t *	pInfo,
		IotTaskPool_t *const	pTaskPool
	)

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.

Parameters

[in]	pInfo	A pointer to the task pool initialization data.
[out]	pTaskPool	A pointer to the task pool handle to be used after initialization. The pointer `pTaskPool` will hold a valid handle only if (IotTaskPool_Create) completes successfully.

Returns

One of the following:

◆ IotTaskPool_Destroy()

IotTaskPoolError_t IotTaskPool_Destroy ( IotTaskPool_t taskPool )

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 IotTaskPool_Create or IotTaskPool_CreateSystemTaskPool. Calling this function release all underlying resources. After calling this function, any job scheduled but not yet executed will be canceled and destroyed. The taskPool instance will no longer be valid after this function returns.

Parameters

[in] taskPool A handle to the task pool, e.g. as returned by a call to IotTaskPool_Create or IotTaskPool_CreateSystemTaskPool. The taskPool instance will no longer be valid after this function returns.

Returns

One of the following:

◆ IotTaskPool_SetMaxThreads()

IotTaskPoolError_t IotTaskPool_SetMaxThreads	(	IotTaskPool_t	taskPool,
		uint32_t	maxThreads
	)

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.

Parameters

[in]	taskPool	A handle to the task pool that must have been previously initialized with a call to IotTaskPool_Create or IotTaskPool_CreateSystemTaskPool.
[in]	maxThreads	The maximum number of threads for the task pool.

Returns

One of the following:

◆ IotTaskPool_CreateJob()

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.

Parameters

[in]	userCallback	A user-specified callback for the job.
[in]	pUserContext	A user-specified context for the callback.
[in,out]	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....

Returns

One of the following:

◆ IotTaskPool_CreateRecyclableJob()

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.

Parameters

[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....

Returns

One of the following:

Warning: A recyclable job should be recycled with a call to IotTaskPool_RecycleJob rather than destroyed.

◆ IotTaskPool_DestroyRecyclableJob()

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.

Parameters

[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.

Returns

One of the following:

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 IotTaskPool_DestroyRecyclableJob is not called our of order.; Calling this function on job that was not previously created with IotTaskPool_CreateRecyclableJob will result in a IOT_TASKPOOL_ILLEGAL_OPERATION error.

◆ IotTaskPool_RecycleJob()

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.

Parameters

[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.

Returns

One of the following:

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.; Attempting to call this function on a statically allocated job will result in IOT_TASKPOOL_ILLEGAL_OPERATION error.; 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 IotTaskPool_DestroyRecyclableJob will result is a memory leak. Statically allocated jobs do not need to be recycled or destroyed.

◆ IotTaskPool_Schedule()

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.

Parameters

[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.

Returns

One of the following:

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.

Example

// 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 );
}

◆ IotTaskPool_ScheduleDeferred()

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.

Parameters

[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.

Returns

One of the following:

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.

◆ IotTaskPool_GetStatus()

IotTaskPoolError_t IotTaskPool_GetStatus	(	IotTaskPool_t	taskPool,
		IotTaskPoolJob_t	job,
		IotTaskPoolJobStatus_t *const	pStatus
	)

This function retrieves the current status of a job.

Parameters

[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.

Returns

One of the following:

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.

◆ IotTaskPool_TryCancel()

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.

Parameters

[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.

Returns

One of the following:

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.

◆ IotTaskPool_GetJobStorageFromHandle()

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.

Parameters

[in] job The job handle.

Returns: A pointer to the storage associated with the job handle job.

Warning: If the job handle used is invalid, the results will be undefined.

◆ IotTaskPool_strerror()

const char* IotTaskPool_strerror ( IotTaskPoolError_t status )

Returns a string that describes an IotTaskPoolError_t.

Like the POSIX 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.

Parameters

[in] status The status to describe.

Returns: A read-only string that describes status.

Warning: The string returned by this function must never be modified.

Macros

Functions

Detailed Description

Function Documentation

◆ IotTaskPool_CreateSystemTaskPool()

◆ IotTaskPool_GetSystemTaskPool()

◆ IotTaskPool_Create()

◆ IotTaskPool_Destroy()

◆ IotTaskPool_SetMaxThreads()

◆ IotTaskPool_CreateJob()

◆ IotTaskPool_CreateRecyclableJob()

◆ IotTaskPool_DestroyRecyclableJob()

◆ IotTaskPool_RecycleJob()

◆ IotTaskPool_Schedule()

◆ IotTaskPool_ScheduleDeferred()

◆ IotTaskPool_GetStatus()

◆ IotTaskPool_TryCancel()

◆ IotTaskPool_GetJobStorageFromHandle()

◆ IotTaskPool_strerror()