Implements the task pool functions in iot_taskpool.h. More...

#include "iot_config.h"
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "platform/iot_threads.h"
#include "platform/iot_clock.h"
#include "private/iot_taskpool_internal.h"

Macros
#define	TASKPOOL_ENTER_CRITICAL() IotMutex_Lock( &( pTaskPool->lock ) )
	Enter a critical section by locking a mutex.

#define	TASKPOOL_EXIT_CRITICAL() IotMutex_Unlock( &( pTaskPool->lock ) )
	Exit a critical section by unlocking a mutex.

#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 (IotTimer_t const pTimer, _taskPoolTimerEvent_t const pFirstTimerEvent)

static void	_timerThread (void *pArgument)

static IotTaskPoolError_t	_performTaskPoolParameterValidation (const IotTaskPoolInfo_t *const pInfo)

static IotTaskPoolError_t	_initTaskPoolControlStructures (const IotTaskPoolInfo_t const pInfo, _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 bool	_IsShutdownStarted (const _taskPool_t *const pTaskPool)

static void	_signalShutdown (_taskPool_t *const pTaskPool, uint32_t threads)

static IotTaskPoolError_t	_scheduleInternal (_taskPool_t const pTaskPool, _taskPoolJob_t const pJob, uint32_t flags)

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)

static IotTaskPoolError_t	_trySafeExtraction (_taskPool_t const pTaskPool, _taskPoolJob_t const pJob, bool atCompletion)

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

IotTaskPoolError_t	IotTaskPool_CreateSystemTaskPool (const IotTaskPoolInfo_t *pInfo)
	Creates the one single instance of the 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 taskPoolHandle)
	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 taskPoolHandle, 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 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 pJob, 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 pJob, IotTaskPoolJobStatus_t *const pStatus)
	This function retrieves the current status of a job. More...

IotTaskPoolError_t	IotTaskPool_TryCancel (IotTaskPool_t taskPoolHandle, IotTaskPoolJob_t pJob, 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
_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...

Detailed Description

Implements the task pool functions in iot_taskpool.h.

Function Documentation

◆ _initJobsCache()

static void _initJobsCache ( _taskPoolCache_t *const pCache )

static

Initializes one instance of a Task pool cache.

Parameters

[in] pCache The pre-allocated instance of the cache to initialize.

◆ _initializeJob()

static void _initializeJob	(	_taskPoolJob_t *const	pJob,
		IotTaskPoolRoutine_t	userCallback,
		void *	pUserContext,
		bool	isStatic
	)

static

Initialize a job.

Parameters

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

◆ _fetchOrAllocateJob()

static _taskPoolJob_t * _fetchOrAllocateJob ( _taskPoolCache_t *const pCache )

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.

Parameters

[in] pCache The instance of the cache to extract the job from.

◆ _recycleJob()

static void _recycleJob	(	_taskPoolCache_t *const	pCache,
		_taskPoolJob_t *const	pJob
	)

static

Recycles one instance of a job into the cache or, if the cache is full, it destroys it.

Parameters

[in]	pCache	The instance of the cache to recycle the job into.
[in]	pJob	The job to recycle.

◆ _destroyJob()

static void _destroyJob ( _taskPoolJob_t *const pJob )

static

Destroys one instance of a job.

Parameters

[in] pJob The job to destroy.

◆ _taskPoolWorker()

static void _taskPoolWorker ( void * pUserContext )

static

The procedure for a task pool worker thread.

Parameters

[in] pUserContext The user context.

◆ _timerEventCompare()

static int32_t _timerEventCompare	(	const IotLink_t *const	pTimerEventLink1,
		const IotLink_t *const	pTimerEventLink2
	)

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.

◆ _rescheduleDeferredJobsTimer()

static void _rescheduleDeferredJobsTimer	(	IotTimer_t *const	pTimer,
		_taskPoolTimerEvent_t *const	pFirstTimerEvent
	)

static

Reschedules the timer for handling deferred jobs to the next timeout.

param[in] pTimer The timer to reschedule. param[in] pFirstTimerEvent The timer event that carries the timeout and job information.

◆ _timerThread()

static void _timerThread ( void * pArgument )

static

The task pool timer procedure for scheduling deferred jobs.

param[in] pArgument An opaque pointer for timer procedure context.

◆ _performTaskPoolParameterValidation()

static IotTaskPoolError_t _performTaskPoolParameterValidation ( const IotTaskPoolInfo_t *const pInfo )

static

Parameter validation for a task pool initialization.

Parameters

[in] pInfo The initialization information for the task pool.

◆ _initTaskPoolControlStructures()

static IotTaskPoolError_t _initTaskPoolControlStructures	(	const IotTaskPoolInfo_t *const	pInfo,
		_taskPool_t *const	pTaskPool
	)

static

Initializes a pre-allocated instance of a task pool.

Parameters

[in]	pInfo	The initialization information for the task pool.
[in]	pTaskPool	The pre-allocated instance of the task pool to initialize.

◆ _createTaskPool()

static IotTaskPoolError_t _createTaskPool	(	const IotTaskPoolInfo_t *const	pInfo,
		_taskPool_t *const	pTaskPool
	)

static

Initializes a pre-allocated instance of a task pool.

Parameters

[in]	pInfo	The initialization information for the task pool.
[out]	pTaskPool	A pointer to the task pool data structure to initialize.

◆ _destroyTaskPool()

static void _destroyTaskPool ( _taskPool_t *const pTaskPool )

static

Destroys one instance of a task pool.

Parameters

[in] pTaskPool The task pool to destroy.

◆ _IsShutdownStarted()

static bool _IsShutdownStarted ( const _taskPool_t *const pTaskPool )

static

Check for the exit condition.

Parameters

[in] pTaskPool The task pool to destroy.

◆ _signalShutdown()

static void _signalShutdown	(	_taskPool_t *const	pTaskPool,
		uint32_t	threads
	)

static

Set the exit condition.

Parameters

[in]	pTaskPool	The task pool to destroy.
[in]	threads	The number of threads active in the task pool at shutdown time.

◆ _scheduleInternal()

static IotTaskPoolError_t _scheduleInternal	(	_taskPool_t *const	pTaskPool,
		_taskPoolJob_t *const	pJob,
		uint32_t	flags
	)

static

Places a job in the dispatch queue.

Parameters

[in]	pTaskPool	The task pool to schedule the job with.
[in]	pJob	The job to schedule.
[in]	flags	The job flags.

◆ _matchJobByPointer()

static bool _matchJobByPointer	(	const IotLink_t *const	pLink,
		void *	pMatch
	)

static

Matches a deferred job in the timer queue with its timer event wrapper.

Parameters

[in]	pLink	A pointer to the timer event link in the timer queue.
[in]	pMatch	A pointer to the job to match.

◆ _tryCancelInternal()

static IotTaskPoolError_t _tryCancelInternal	(	_taskPool_t *const	pTaskPool,
		_taskPoolJob_t *const	pJob,
		IotTaskPoolJobStatus_t *const	pStatus
	)

static

Tries to cancel a job.

Parameters

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

◆ _trySafeExtraction()

static IotTaskPoolError_t _trySafeExtraction	(	_taskPool_t *const	pTaskPool,
		_taskPoolJob_t *const	pJob,
		bool	atCompletion
	)

static

Try to safely cancel and/or remove a job from the cache when the user calls API out of order.

Parameters

[in]	pTaskPool	The task pool to safely extract a job from.
[in]	pJob	The job to extract.
[in]	atCompletion	A flag to indicate whether the job is being scheduled or was completed already.

◆ 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_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_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.

Variable Documentation

◆ _IotSystemTaskPool

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

Doxygen should ignore this section.

Macros

Functions

Variables

Detailed Description

Function Documentation

◆ _initJobsCache()

◆ _initializeJob()

◆ _fetchOrAllocateJob()

◆ _recycleJob()

◆ _destroyJob()

◆ _taskPoolWorker()

◆ _timerEventCompare()

◆ _rescheduleDeferredJobsTimer()

◆ _timerThread()

◆ _performTaskPoolParameterValidation()

◆ _initTaskPoolControlStructures()

◆ _createTaskPool()

◆ _destroyTaskPool()

◆ _IsShutdownStarted()

◆ _signalShutdown()

◆ _scheduleInternal()

◆ _matchJobByPointer()

◆ _tryCancelInternal()

◆ _trySafeExtraction()

◆ IotTaskPool_GetSystemTaskPool()

◆ IotTaskPool_CreateSystemTaskPool()

◆ 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()

Variable Documentation

◆ _IotSystemTaskPool