NOTE: The project and documentation presented on this page is a work in progress so provided as a separate zip file download.  It will be released in the main FreeRTOS download following full review and completion of this documentation.

IoT Task Pool
Library and Demo Application


On this page:

  1. The IoT Task Pool Library
  2. The IoT Task Pool Demo Application

 

Introduction

The IoT Task Pool library is a utility library that provides a “pool” of tasks that can be shared by the MCU application and FreeRTOS IoT libraries. This pooling of tasks alleviates the need for each library to create and manage its own tasks.

The FreeRTOS IoT libraries can be used individually or collectively to create locally connected or internet connected MCU applications.  Each library can be freely used and is distributed under the MIT Open Source License.

 

Task Pool Terminology

Task Pool

A task pool (or thread pool) is a set of tasks that can asynchronously execute functions (jobs) on behalf of other tasks. This concept is similar to how the FreeRTOS xTimerPendFunctionCall() API function enables a task to defer the execution of a function to the RTOS daemon task. While FreeRTOS contains only one Daemon task, a task pool may contain multiple tasks that execute in parallel.

System Task Pool

A (system task pool) is a task pool that is managed by the IoT Task Pool library. Task pools are divided into two categories (system and application defined). In the demo download provided, the IoT Task Pool library is optimized for MCU development by implementing only the system task pool. Users can switch to the full task pool implementation, which also implements application defined task pools, if that additional capability is needed.

Worker Tasks

Worker tasks make up the task pool and execute callback functions on behalf of other tasks. These tasks are responsible for executing the jobs that are sent to the task pool.

Jobs

Jobs are data structures that include a callback function that will be executed by a worker task once they have been scheduled. A job must be created before it can be scheduled by the task pool for execution.

Scheduling Jobs

Jobs can be scheduled to be run by a worker task immediately that a worker task is available, or deferred to run at a later time. If a job is scheduled to run immediately when all the worker tasks are already busy then the job is queued until a worker task becomes available.

Job Queue

The job queue contains scheduled jobs. Jobs are removed from the queue through execution by the worker tasks. Jobs can also be removed through cancellation.

Deferred Jobs

Deferred jobs are jobs that are executed at a specified time after they have been sent to the task pool. This is analogous to a FreeRTOS software timer, which is a callback function set to execute after a specified delay.

Recyclable Jobs and Job Cache

Recyclable jobs are jobs in the system task pool memory that can be reused continuously and persist in memory between executions. The job cache stores a recyclable job if it is inactive. The job cache’s maximum capacity is set by the IOT_TASKPOOL_JOBS_RECYCLE_LIMIT constant in iot_config.h. Recyclable and non-recyclable jobs are demonstrated by the prvExample_ReuseRecyclableJobFromLowPriorityTask() and prvExample_BasicSingleJob() functions in the task pool demo application respectively.

Job Context

The job context is data that is specific to the job and it is passed as a parameter to the job’s callback function.

 

IoT Task Pool Implementations

The IoT Task Pool library has many use cases, including for large Linux application development. Typical FreeRTOS use cases do not require its full functionality, so an optimized version specifically for FreeRTOS is provided in the demo. The optimized version, the task pool:

  • Only supports a single task pool (system task pool) at a time.
  • Does not auto-scale by dynamically adding more tasks if the number of tasks in the pool becomes exhausted. Instead, the number of tasks in the pool is fixed at compile time by the IOT_TASKPOOL_NUMBER_OF_WORKERS constant in iot_config.h.
  • Cannot be shut down – it exists for the lifetime of the application.

Users can switch to the full task pool implementation if the full capability is needed.

 

 

IoT Task Pool API Reference

Doxygen API documentation.

 

IoT Task Pool Demo Project

 

Introduction

The task pool demo project uses the FreeRTOS Windows port, enabling it to be built and evaluated with the free Community version of Visual Studios on Windows, so without the need for any particular MCU hardware.

 

Source Code Organization


Click to enlarge

The project that builds the task pool demo is called task_pool_demo.sln and is located in the /FreeRTOS-Plus/Demo/FreeRTOS_IoT_Libraries/task_pool of the main FreeRTOS download. NOTE:The project is not in the main FreeRTOS download yet so for now is provided as a separate zip file download.

Notes: The demo project is an extension to the TCP/IP Starter project that has been provided with FreeRTOS for several years. While the IoT Task Pool library is not directly related to connectivity, the MQTT demo project builds on the task pool project and depends on both the task pool and TCP/IP stack. The figure on the right (click to enlarge) shows the files added into the TCP/IP starter project to integrate the task pool library.

 

Building the Demo Project

The demo project uses the free community edition of Visual Studio

To build the demo:

  1. Open the /FreeRTOS-Plus/Demo/FreeRTOS_IoT_Libraries/task-pool/task_pool_demo.sln Visual Studio solution file from within the Visual Studio IDE
  2. Select ‘build solution’ from the IDE’s ‘build’ menu (or press F7).

 

Functionality

The demo creates a single application task that loops through a set of examples. The examples introduce task pool concepts progressing from the simplest use cases to more advanced scenarios.

All of the jobs created in the demo use the same callback function. The callback sends a direct to task notification to the demo task to let the task know the job callback has been executed.

 

The Callback Function used by the Jobs in this Demo
static void prvSimpleTaskNotifyCallback( IotTaskPool_t pTaskPool,
                                         IotTaskPoolJob_t pJob,
                                         void *pUserContext )
{
    /* The jobs context is the handle of the task to which a
     * notification should be sent.
     */
    TaskHandle_t xTaskToNotify = ( TaskHandle_t ) pUserContext;

    /* Remove warnings about unused parameters. */
    ( void ) pTaskPool;
    ( void ) pJob;

    /* Notify the task that created this job. */
    xTaskNotifyGive( xTaskToNotify );
}

 

The screenshot below shows the expected output when the demo is executing correctly. Click to enlarge.


Click to enlarge

The following sub-sections describe the individual examples.

Creating a Job that Immediately Executes

The function prvExample_BasicSingleJob() demonstrates the simplest use case where IotTaskPool_CreateJob is used to create a non-persistent job that is then scheduled for immediate execution by a call to IotTaskPool_Schedule(). The Job’s data structure is allocated on the stack, so the job does not need to be dynamically allocated or freed.

A worker task will have a higher priority than the task that calls prvExample_BasicSingleJob(), so the worker task will preempt the calling task, resulting in the job’s callback executing immediately.

A simplified version of the function is shown below with some error checking removed. See the source code for the full version.

 

static void prvExample_BasicSingleJob( void )
{
    IotTaskPoolJobStorage_t xJobStorage;
    IotTaskPoolJob_t xJob;
    uint32_t ulReturn;
    const uint32_t ulNoFlags = 0UL;
    const TickType_t xNoDelay = ( TickType_t ) 0;

    /* Create and schedule a job using the handle of
     * this task as the job's context and the function
     * that sends a notification to the task handle as
     * the jobs callback function. This is not a recyclable
     * job so the storage required to hold information
     * about the job is provided by this task - in this
     * case the storage is on the stack of this task so no 
     * memory is allocated dynamically but the stack frame
     * must remain in scope for the lifetime of the job.
     */
    IotTaskPool_CreateJob(
        /* Callback function. */
        prvSimpleTaskNotifyCallback,

        /* Job context, in this case the handle of the calling
         * task so the callback knows which task to send a
         * notification to.
         */
        ( void * ) xTaskGetCurrentTaskHandle(),

        &xJobStorage,
        &xJob );

    /* In the full task pool implementation the first parameter
     * is used to pass the handle of the task pool to schedule.
     * The lean task pool implementation used in this demo only
     * supports a single task pool, which is created internally
     * within the library, so the first parameter is NULL.
     */
    IotTaskPool_Schedule( NULL, xJob, ulNoFlags );

    /* Look for the notification coming from the job's callback
     * function. The priority of the task pool worker task that
     * executes the callback is higher than the priority of this
     * task so a block time is not needed - the task pool worker
     * task pre-empts this task and sends the notification (from
     * the job's callback) as soon as the job is scheduled.
     */
    ulReturn = ulTaskNotifyTake( pdTRUE, xNoDelay );
    configASSERT( ulReturn );
}

 

Creating a Deferred Job

The function prvExample_DeferredJobAndCancellingJobs() is similar to prvExample_BasicSingleJob(), but uses IotTaskPool_ScheduleDeferred() in place of IotTaskPool_Schedule(). This will create a job that does not execute immediately, but at a time deferred to the future.

prvExample_DeferredJobAndCancellingJobs() also demonstrates how a scheduled job can be cancelled before it has been executed.

A simplified version of the function is shown below with some error checking removed. See the source code for the full version.

 

static void prvExample_DeferredJobAndCancellingJobs( void )
{
    IotTaskPoolJobStorage_t xJobStorage;
    IotTaskPoolJob_t xJob;
    uint32_t ulReturn;
    const uint32_t ulShortDelay_ms = 100UL;
    const TickType_t xAllowableMargin = ( TickType_t ) 5;
    TickType_t xTimeBefore, xElapsedTime, xShortDelay_ticks;
    IotTaskPoolJobStatus_t xJobStatus;

    /* Create a job using the handle of this task as the job's
     * context and the function that sends a notification to
     * the task handle as the jobs callback function. The job
     * is created using storage allocated on the stack of this
     * function - so no memory is allocated.
     */
   IotTaskPool_CreateJob(
        /* Callback function. */
        prvSimpleTaskNotifyCallback,

        /* Job context, in this case the handle of the calling
         * task so the callback knows which task to send a
         * notification to.
         */
        ( void * ) xTaskGetCurrentTaskHandle(),

        &xJobStorage,
        &xJob );

    /* Schedule the job to run its callback in xShortDelay_ms
     * milliseconds time. In the full task pool implementation
     * the first parameter is used to pass the handle of the
     * task pool to schedule. The lean task pool implementation
     * used in this demo only supports a single task pool, which
     * is created internally within the library, so the first
     * parameter is NULL.
     */
    IotTaskPool_ScheduleDeferred( NULL, xJob, ulShortDelay_ms );

    /* The scheduled job should not have executed yet, so 
     * expect the job's status to be 'deferred'.
     */
    IotTaskPool_GetStatus( NULL, xJob, &xJobStatus );
    configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_DEFERRED );

    /* As the job has not yet been executed it can be stopped. */
    IotTaskPool_TryCancel( NULL, xJob, &xJobStatus );

    IotTaskPool_GetStatus( NULL, xJob, &xJobStatus );
    configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_CANCELED );

    /* Schedule the job again, and this time wait until its 
     * callback is executed (the callback function sends a 
     * notification to this task) to see that it executes at 
     * the right time. Remember the time now so the time between 
     * scheduling and the callback executing can be measured. 
     */
    xTimeBefore = xTaskGetTickCount();

    IotTaskPool_ScheduleDeferred( NULL, xJob, ulShortDelay_ms );

    /* Wait twice the deferred execution time to ensure the
     * callback is executed before the call below times out.
     */
    ulReturn = ulTaskNotifyTake(
        pdTRUE,
        pdMS_TO_TICKS( ulShortDelay_ms * 2UL ) );

    xElapsedTime = xTaskGetTickCount() - xTimeBefore;

    /* A single notification should not have been received... */
    configASSERT( ulReturn == 1 );

    /* ...and the time since scheduling the job should be
     * greater than or equal to the deferred execution time
     * - which is converted to ticks for comparison.
     */
    xShortDelay_ticks = pdMS_TO_TICKS( ulShortDelay_ms );

    configASSERT( ( xElapsedTime >= xShortDelay_ticks ) &&
                  ( xElapsedTime < ( xShortDelay_ticks + xAllowableMargin ) ) );

}

 

Creating and Deleting a Recyclable Job

prvExample_BasicRecyclableJob() demonstrates a similar functionality to prvExample_BasicSingleJob(), but uses IotTaskPool_CreateRecyclableJob(), to create a recyclable job. The recyclable job will come from a job cache within the system task pool. If there are no available jobs in the cache but there is free memory, a new job will be created in the cache. It is recommended to allocate all of the memory upfront within the system task pool.

prvExample_BasicRecycleableJob() also calls IotTaskPool_DestroyRecyclableJob() to demonstrate how to delete a recyclable job. This is not a common FreeRTOS kernel use case.

A simplified version of the function is shown below with some error checking removed. See the source code for the full version.

 

static void prvExample_BasicRecyclableJob( void )
{
    IotTaskPoolJob_t xJob;
    uint32_t ulReturn;
    const uint32_t ulNoFlags = 0UL;
    const TickType_t xNoDelay = ( TickType_t ) 0;

    /* Create and schedule a job using the handle of this task as the
     * job's context and the function that sends a notification to
     * the task handle as the jobs callback function. The job is created
     * as a recyclable job and in this case the memory used to hold
     * the job status is allocated inside the create function. As the
     * job is persistent it can be used multiple times, as demonstrated
     * in other examples within this demo. In the full task pool
     * implementation the first parameter is used to pass the handle of
     * the task pool this recyclable job is to be associated with. In
     * the lean implementation of the task pool used by this demo there
     * is only one task pool (the system task pool created within the
     * task pool library) so the first parameter is NULL.
     */
    IotTaskPool_CreateRecyclableJob(
        NULL,

        /* Callback function. */
        prvSimpleTaskNotifyCallback,

        /* Job context, in this case the handle of the calling task so
         * the callback knows which task to send a notification to.
         */
        (void * ) xTaskGetCurrentTaskHandle(),

        &xJob );

    /* In the full task pool implementation the first parameter is used
     * to pass the handle of the task pool to schedule. The lean task
     * pool implementation used in this demo only supports a single task
     * pool, which is created internally within the library, so the first
     * parameter is NULL.
     */
    IotTaskPool_Schedule( NULL, xJob, ulNoFlags );

    /* Look for the notification coming from the job's callback function.
     * The priority of the task pool worker task that executes the callback
     * is higher than the priority of this task so a block time is not 
     * needed - the task pool worker task pre-empts this task and sends the
     * notification (from the job's callback) as soon as the job is scheduled.
     */
    ulReturn = ulTaskNotifyTake( pdTRUE, xNoDelay );

    configASSERT( ulReturn );

    /* Clean up recyclable job. In the full implementation of the task pool
     * the first parameter is used to pass a handle to the task pool the job
     * is associated with. In the lean implementation of the task pool used
     * by this demo there is only one task pool (the system task pool created
     * in the task pool library itself) so the first parameter is NULL.
     */
    IotTaskPool_DestroyRecyclableJob( NULL, xJob );

} 

 

Reusing Recyclable Jobs (Worker Task has Higher Priority)

prvExample_ReuseRecyclableJobFromLowPriorityTask() demonstrates how to continuously use (or recycle) a recyclable job. It also demonstrates the effect of task prioritization when the priority of the worker task is higher than the priority of the task for deferred jobs.

A simplified version of the function is shown below with some error checking removed. See the source code for the full version.

 

static void prvExample_ReuseRecyclableJobFromLowPriorityTask( void )
{
    IotTaskPoolError_t xResult;
    uint32_t x, xIndex, ulNotificationValue;
    const uint32_t ulNoFlags = 0UL;

    IotTaskPoolJob_t xJobs[ tpJOBS_TO_CREATE ];
    IotTaskPoolJobStatus_t xJobStatus;

    /* Create tpJOBS_TO_CREATE jobs using the handle of this task as the
     * job's context and the function that sends a notification to the
     * task handle as the jobs callback function. The jobs are created
     * as a recyclable job and in this case the memory to store the job
     * information is allocated within the create function as at this
     * time there are no recyclable jobs in the task pool jobs cache. As
     * the jobs are persistent they can be used multiple times. In the
     * full task pool implementation the first parameter is used to pass
     * the handle of the task pool this recyclable job is to be associated
     * with. In the lean implementation of the task pool used by this demo
     * there is only one task pool (the system task pool created within
     * the task pool library) so the first parameter is NULL.
     */
    for( x = 0; x < tpJOBS_TO_CREATE; x++ )
    {
        IotTaskPool_CreateRecyclableJob(
            NULL,

            /* Callback function. */
            prvSimpleTaskNotifyCallback,

            /* Job context, in this case the handle of the calling task
             * so the callback knows which task to send a notification to.
             */
            ( void * ) xTaskGetCurrentTaskHandle(),

            &( xJobs[ x ] ) );
    }

    /* Demonstrate that the jobs can be recycled by performing twice
     * the number of iterations of scheduling jobs than there actually
     * are created jobs. This works because the task pool task priorities
     * are above the priority of this task, so the tasks that run the
     * jobs pre-empt this task as soon as a job is ready.
     */
    for( x = 0; x < ( tpJOBS_TO_CREATE * 2UL ); x++ )
    {
        /* Make sure array index does not go out of bounds. */
        xIndex = x % tpJOBS_TO_CREATE;

        IotTaskPool_Schedule( NULL, xJobs[ xIndex ], ulNoFlags );

        /* The priority of the task pool task(s) is higher than the priority
         * of this task, so the job's callback function should have already
         * executed, sending a notification to this task, and incrementing
         * this task's notification value.
         */
        xTaskNotifyWait(
            0UL, /* Don't clear any bits on entry. */            
            0UL, /* Don't clear any bits on exit. */            
            &ulNotificationValue, /* Obtain the notification value. */            
            0UL ); /* No block time, return immediately. */
        
        configASSERT( ulNotificationValue == ( x + 1 ) );

        /* The job's callback has executed so the job is now completed. */
        IotTaskPool_GetStatus( NULL, xJobs[ xIndex ], &xJobStatus );

        configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_COMPLETED );

        /* To leave the list of jobs empty we can stop re-creating jobs
         * half way through iterations of this loop.
         */
        if( x < tpJOBS_TO_CREATE )
        {
            /* Recycle the job so it can be used again. In the full
             * task pool implementation the first parameter is used
             * to pass the handle of the task pool this job will be
             * associated with. In this lean task pool implementation
             * only the system task pool exists (the task pool created
             * internally to the task pool library) so the first
             * parameter is just passed as NULL.
             */
            IotTaskPool_RecycleJob( NULL, xJobs[ xIndex ] );

            xResult = IotTaskPool_CreateRecyclableJob(
                NULL,

                /* Callback function to use. */
                prvSimpleTaskNotifyCallback,

                /* Job context, in this case the handle of the calling
                 * task so the callback knows which task to send a
                 * notification to.
                 */
                ( void * ) xTaskGetCurrentTaskHandle(),

                &( xJobs[ xIndex ] ) );
            configASSERT( xResult == IOT_TASKPOOL_SUCCESS );
        }
    }

    /* Clear all the notification value bits again. */
    xTaskNotifyWait(
        /* Clear all bits on entry - portMAX_DELAY is used as it is a
         * portable way of having all bits set. */
        portMAX_DELAY,
        0UL, /* Don't clear any bits on exit. */        
        NULL, /* Don't need the notification value this time. */ 
        0UL );/* No block time, return immediately. */    

    /* Clean up all the recyclable job. In the full implementation
     * of the task pool the first parameter is used to pass a handle
     * to the task pool the job is associated with. In the lean
     * implementation of the task pool used by this demo there is
     * only one task pool (the system task pool created in the task
     * pool library itself) so the first parameter is NULL. */
    for( x = 0; x < tpJOBS_TO_CREATE; x++ )
    {
        IotTaskPool_DestroyRecyclableJob( NULL, xJobs[ x ] );
    }
}

 

Re-using Recyclable Jobs (Worker Tasks have Lower Priority)

prvExample_ReuseRecyclableJobFromHighPriorityTask() demonstrates how to continuously use (or recycle) a recyclable job. It demonstrates the effect of task prioritization when the priority of the worker task is lower than the priority of the task for deferred jobs.

A simplified version of the function is shown below with some error checking removed. See the source code for the full version.

 

static prvExample_ReuseRecyclableJobFromHighPriorityTask( void )
{
    IotTaskPoolError_t xResult;
    uint32_t x, ulNotificationValue;
    const uint32_t ulNoFlags = 0UL;
    IotTaskPoolJob_t xJobs[ tpJOBS_TO_CREATE ];

    IotTaskPoolJobStorage_txJobStorage[ tpJOBS_TO_CREATE ];
    TickType_t xShortDelay = pdMS_TO_TICKS( 150 );
    IotTaskPoolJobStatus_t xJobStatus;

    /* prvExample_ReuseRecyclableJobFromLowPriorityTask() executes in
     * a task that has a lower [task] priority than the task pool's worker
     * tasks. Therefore a talk pool worker preempts the task that calls
     * prvExample_ReuseRecyclableJobFromHighPriorityTask() as soon as the
     * job is scheduled. prvExample_ReuseRecyclableJobFromHighPriorityTask()
     * reverses the priorities -
     * prvExample_ReuseRecyclableJobFromHighPriorityTask() raises its priority
     * to above the task pool's worker tasks, so the worker tasks do not
     * execute until the calling task enters the blocked state. First raise
     * the priority - passing NULL means raise the priority of the calling task.
     */
    vTaskPrioritySet( NULL, tpTASK_POOL_WORKER_PRIORITY + 1 );

    /* Create tpJOBS_TO_CREATE jobs using the handle of this task as the job's
     * context and the function that sends a notification to the task handle
     * as the jobs callback function.
     */
    for( x = 0; x < tpJOBS_TO_CREATE; x++ )
    {
        IotTaskPool_CreateJob(
            /* Callback function. */
            prvSimpleTaskNotifyCallback,

            /* Job context, in this case the handle of the calling task so
             * the callback knows which task to send a notification to.
             */
            ( void * ) xTaskGetCurrentTaskHandle(),
            &( xJobStorage[ x ] ),
            &( xJobs[ x ] ) );
    }

    for( x = 0; x < tpJOBS_TO_CREATE; x++ )
    {
        /* Schedule the next job. */
        IotTaskPool_Schedule( NULL, xJobs[ x ], ulNoFlags );

        /* Although scheduled, the job's callback has not executed, so
         * the job reports itself as scheduled.
         */
        IotTaskPool_GetStatus( NULL, xJobs[ x ], &xJobStatus );
        configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_SCHEDULED );

        /* The priority of the task pool task(s) is lower than the priority of
         * this task, so the job's callback function should not have executed
         * yes, so don't expect the notification value for this task to have
         * changed.
         */
        xTaskNotifyWait(
            0UL, /* Don't clear any bits on entry. */            
            0UL, /* Don't clear any bits on exit. */            
            &ulNotificationValue, /* Obtain the notification value. */            
            0UL ); /* No block time, return immediately. */
        
        configASSERT( ulNotificationValue == 0 );
    }

    /* At this point there are tpJOBS_TO_CREATE scheduled, but none have executed
     * their callbacks because the priority of this task is higher than the
     * priority of the task pool worker threads. When this task blocks to wait for
     * a notification a worker thread will be able to executes - but as soon as its
     * callback function sends a notification to this task this task will preempt
     * it (because it has a higher priority) so this task only expects to receive one
     * notification at a time.
     */
    for( x = 0; x < tpJOBS_TO_CREATE; x++ )
    {
        xTaskNotifyWait(
            0UL, /* Don't clear any bits on entry. */            
            0UL, /* Don't clear any bits on exit. */            
            &ulNotificationValue, /* Obtain the notification value. */            
            xShortDelay ); /* delay to allow worker task to execute. */
        
        configASSERT( ulNotificationValue == ( x + 1 ) );
    }

    /* All the scheduled jobs have now executed, so waiting for another notification
     * should timeout without the notification value changing. */
    xTaskNotifyWait(
        0UL, /* Don't clear any bits on entry. */        
        0UL, /* Don't clear any bits on exit. */        
        &ulNotificationValue, /* Obtain the notification value. */        
        xShortDelay ); /* Short delay to allow a task pool worker to execute. */
    
    configASSERT( ulNotificationValue == x );

    /* Reset the priority of this task and clear the notifications ready for the next
     * example. */
    vTaskPrioritySet( NULL, tskIDLE_PRIORITY );

    /* Clear all the notification value bits again. */
    xTaskNotifyWait(

        /* Clear all bits on entry - portMAX_DELAY is used as it is a portable way of
         * having all bits set.
         */
        portMAX_DELAY,
        0UL, /* Don't clear any bits on exit. */        
        NULL, /* Don't need the notification value this time. */        
        0UL ); /* No block time, return immediately. */