IotTaskPool_Schedule

This function schedules a job created with IotTaskPool_CreateJob or IotTaskPool_CreateRecyclableJob against the task pool pointed to by taskPool.

IotTaskPoolError_t IotTaskPool_Schedule( IotTaskPool_t taskPool,
                                         IotTaskPoolJob_t job,
                                         uint32_t flags );

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:

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

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