/* * FreeRTOS Kernel V10.2.1 * Copyright (C) 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. * * Permission is hereby granted, free of charge, to any person obtaining a copy of * this software and associated documentation files (the "Software"), to deal in * the Software without restriction, including without limitation the rights to * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of * the Software, and to permit persons to whom the Software is furnished to do so, * subject to the following conditions: * * The above copyright notice and this permission notice shall be included in all * copies or substantial portions of the Software. * * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. * * http://www.FreeRTOS.org * http://aws.amazon.com/freertos * * 1 tab == 4 spaces! */ /* Kernel includes. */ #include "FreeRTOS.h" #include "task.h" /* Standard includes. */ #include /* IoT SDK includes. */ #include "iot_taskpool.h" /* The priority at which that tasks in the task pool (the worker tasks) get created. */ #define tpTASK_POOL_WORKER_PRIORITY 1 /* * Prototypes for the functions that demonstrate the task pool API. * See the implementation of the prvTaskPoolDemoTask() function within this file * for a description of the individual functions. A configASSERT() is hit if * any of the demos encounter any unexpected behaviour. */ static void prvExample_BasicSingleJob( void ); static void prvExample_DeferredJobAndCancellingJobs( void ); static void prvExample_BasicRecyclableJob( void ); static void prvExample_ReuseRecyclableJobFromLowPriorityTask( void ); static void prvExample_ReuseRecyclableJobFromHighPriorityTask( void ); /* * Prototypes of the callback functions used in the examples. The callback * simply sends a signal (in the form of a direct task notification) to the * prvTaskPoolDemoTask() task to let the task know that the callback execute. * The handle of the prvTaskPoolDemoTask() task is not accessed directly, but * instead passed into the task pool job as the job's context. */ static void prvSimpleTaskNotifyCallback( IotTaskPool_t pTaskPool, IotTaskPoolJob_t pJob, void *pUserContext ); /* * The task used to demonstrate the task pool API. This task just loops through * each demo in turn. */ static void prvTaskPoolDemoTask( void *pvParameters ); /*-----------------------------------------------------------*/ /* Parameters used to create the system task pool - see TBD for more information * as the task pool used in this example is a slimmed down version of the full * library - the slimmed down version being intended specifically for FreeRTOS * kernel use cases. */ static const IotTaskPoolInfo_t xTaskPoolParameters = { /* Minimum number of threads in a task pool. * Note the slimmed down version of the task * pool used by this library does not autoscale * the number of tasks in the pool so in this * case this sets the number of tasks in the * pool. */ 2, /* Maximum number of threads in a task pool. * Note the slimmed down version of the task * pool used by this library does not autoscale * the number of tasks in the pool so in this * case this parameter is just ignored. */ 2, /* Stack size for every task pool thread - in * bytes, hence multiplying by the number of bytes * in a word as configMINIMAL_STACK_SIZE is * specified in words. */ configMINIMAL_STACK_SIZE * sizeof( portSTACK_TYPE ), /* Priority for every task pool thread. */ tpTASK_POOL_WORKER_PRIORITY, }; /*-----------------------------------------------------------*/ void vStartSimpleTaskPoolDemo( void ) { /* This example uses a single application task, which in turn is used to * create and send jobs to task pool tasks. */ xTaskCreate( prvTaskPoolDemoTask, /* Function that implements the task. */ "PoolDemo", /* Text name for the task - only used for debugging. */ configMINIMAL_STACK_SIZE, /* Size of stack (in words, not bytes) to allocate for the task. */ NULL, /* Task parameter - not used in this case. */ tskIDLE_PRIORITY, /* Task priority, must be between 0 and configMAX_PRIORITIES - 1. */ NULL ); /* Used to pass out a handle to the created task - not used in this case. */ } /*-----------------------------------------------------------*/ static void prvTaskPoolDemoTask( void *pvParameters ) { IotTaskPoolError_t xResult; uint32_t ulLoops = 0; /* Remove compiler warnings about unused parameters. */ ( void ) pvParameters; /* The task pool must be created before it can be used. The system task * pool is the task pool managed by the task pool library itself - the storage * used by the task pool is provided by the library. */ xResult = IotTaskPool_CreateSystemTaskPool( &xTaskPoolParameters ); configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); /* Attempting to create the task pool again should then appear to succeed * (in case it is initialised by more than one library), but have no effect. */ xResult = IotTaskPool_CreateSystemTaskPool( &xTaskPoolParameters ); configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); for( ;; ) { /* Demonstrate the most basic use case where a non persistent job is * created and scheduled to run immediately. The task pool worker tasks * (in which the job callback function executes) have a priority above the * priority of this task so the job's callback executes as soon as it is * scheduled. */ prvExample_BasicSingleJob(); /* Demonstrate a job being scheduled to run at some time in the * future, and how a job scheduled to run in the future can be cancelled * if it has not yet started executing. */ prvExample_DeferredJobAndCancellingJobs(); /* Demonstrate the most basic use of a recyclable job. This is similar * to prvExample_BasicSingleJob() but using a recyclable job. Creating a * recyclable job will re-use a previously created and now spare job from * the task pool's job cache if one is available, or otherwise dynamically * create a new job if a spare job is not available in the cache but space * remains in the cache. */ prvExample_BasicRecyclableJob(); /* Demonstrate a recyclable job being created, used, and then re-used. * In this the task pool worker tasks (in which the job callback * functions execute) have a priority above the priority of this task so * the job's callback functions execute as soon as they are scheduled. */ prvExample_ReuseRecyclableJobFromLowPriorityTask(); /* Again demonstrate a recyclable job being created, used, and then * re-usedbut this time the priority of the task pool worker tasks (in * which the job callback functions execute) are lower than the priority * of this task so the job's callback functions don't execute until this * task enters the blocked state. */ prvExample_ReuseRecyclableJobFromHighPriorityTask(); ulLoops++; if( ( ulLoops % 10UL ) == 0 ) { configPRINTF( ( "prvTaskPoolDemoTask() performed %u iterations without hitting an assert.\r\n", ulLoops ) ); fflush( stdout ); } } } /*-----------------------------------------------------------*/ 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 ); } /*-----------------------------------------------------------*/ static void prvExample_BasicSingleJob( void ) { IotTaskPoolJobStorage_t xJobStorage; IotTaskPoolJob_t xJob; IotTaskPoolError_t xResult; uint32_t ulReturn; const uint32_t ulNoFlags = 0UL; const TickType_t xNoDelay = ( TickType_t ) 0; size_t xFreeHeapBeforeCreatingJob = xPortGetFreeHeapSize(); IotTaskPoolJobStatus_t xJobStatus; /* Don't expect any notifications to be pending yet. */ configASSERT( ulTaskNotifyTake( pdTRUE, xNoDelay ) == 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 job's 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. */ xResult = IotTaskPool_CreateJob( prvSimpleTaskNotifyCallback, /* Callback function. */ ( void * ) xTaskGetCurrentTaskHandle(), /* Job context. */ &xJobStorage, &xJob ); configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); /* The job has been created but not scheduled so is now ready. */ IotTaskPool_GetStatus( NULL, xJob, &xJobStatus ); configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_READY ); /* This is not a persistent (recyclable) job and its storage is on the * stack of this function, so the amount of heap space available should not * have changed since entering this function. */ configASSERT( xFreeHeapBeforeCreatingJob == xPortGetFreeHeapSize() ); /* 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. */ xResult = IotTaskPool_Schedule( NULL, xJob, ulNoFlags ); configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); /* 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 preempts this task and sends the notification (from the job's * callback) as soon as the job is scheduled. */ ulReturn = ulTaskNotifyTake( pdTRUE, xNoDelay ); configASSERT( ulReturn ); /* The job's callback has executed so the job has now completed. */ IotTaskPool_GetStatus( NULL, xJob, &xJobStatus ); configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_COMPLETED ); } /*-----------------------------------------------------------*/ static void prvExample_DeferredJobAndCancellingJobs( void ) { IotTaskPoolJobStorage_t xJobStorage; IotTaskPoolJob_t xJob; IotTaskPoolError_t xResult; uint32_t ulReturn; const uint32_t ulShortDelay_ms = 100UL; const TickType_t xNoDelay = ( TickType_t ) 0, xAllowableMargin = ( TickType_t ) 5; /* Large margin for Windows port, which is not real time. */ TickType_t xTimeBefore, xElapsedTime, xShortDelay_ticks; size_t xFreeHeapBeforeCreatingJob = xPortGetFreeHeapSize(); IotTaskPoolJobStatus_t xJobStatus; /* Don't expect any notifications to be pending yet. */ configASSERT( ulTaskNotifyTake( pdTRUE, xNoDelay ) == 0 ); /* 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 job's callback * function. The job is created using storage allocated on the stack of this * function - so no memory is allocated. */ xResult = IotTaskPool_CreateJob( prvSimpleTaskNotifyCallback, /* Callback function. */ ( void * ) xTaskGetCurrentTaskHandle(), /* Job context. */ &xJobStorage, &xJob ); configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); /* The job has been created but not scheduled so is now ready. */ IotTaskPool_GetStatus( NULL, xJob, &xJobStatus ); configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_READY ); /* This is not a persistent (recyclable) job and its storage is on the * stack of this function, so the amount of heap space available should not * have changed since entering this function. */ configASSERT( xFreeHeapBeforeCreatingJob == xPortGetFreeHeapSize() ); /* Schedule the job to run its callback in ulShortDelay_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. */ xResult = IotTaskPool_ScheduleDeferred( NULL, xJob, ulShortDelay_ms ); configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); /* The scheduled job should not have executed yet, so don't expect any * notifications and expect the job's status to be 'deferred'. */ ulReturn = ulTaskNotifyTake( pdTRUE, xNoDelay ); configASSERT( ulReturn == 0 ); IotTaskPool_GetStatus( NULL, xJob, &xJobStatus ); configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_DEFERRED ); /* As the job has not yet been executed it can be cancelled. */ xResult = IotTaskPool_TryCancel( NULL, xJob, &xJobStatus ); configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); 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. */ xTimeBefore = xTaskGetTickCount(); xResult = IotTaskPool_ScheduleDeferred( NULL, xJob, ulShortDelay_ms ); configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); /* 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 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 ) ) ); } /*-----------------------------------------------------------*/ static void prvExample_BasicRecyclableJob( void ) { IotTaskPoolJob_t xJob; IotTaskPoolError_t xResult; uint32_t ulReturn; const uint32_t ulNoFlags = 0UL; const TickType_t xNoDelay = ( TickType_t ) 0; size_t xFreeHeapBeforeCreatingJob = xPortGetFreeHeapSize(); /* Don't expect any notifications to be pending yet. */ configASSERT( ulTaskNotifyTake( pdTRUE, xNoDelay ) == 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 job's 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. */ xResult = IotTaskPool_CreateRecyclableJob( NULL, prvSimpleTaskNotifyCallback, (void * ) xTaskGetCurrentTaskHandle(), &xJob ); configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); /* This recyclable job is persistent, and in this case created dynamically, * so expect there to be less heap space than when entering the function. */ configASSERT( xPortGetFreeHeapSize() < xFreeHeapBeforeCreatingJob ); /* 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. */ xResult = IotTaskPool_Schedule( NULL, xJob, ulNoFlags ); configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); /* 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 preempts 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 ); /* Once the job has been deleted the memory used to hold the job is * returned, so the available heap should be exactly as when entering this * function. */ configASSERT( xPortGetFreeHeapSize() == xFreeHeapBeforeCreatingJob ); } /*-----------------------------------------------------------*/ static void prvExample_ReuseRecyclableJobFromLowPriorityTask( void ) { IotTaskPoolError_t xResult; uint32_t ulNotificationValue; const uint32_t ulNoFlags = 0UL; const TickType_t xNoDelay = ( TickType_t ) 0; IotTaskPoolJob_t xJob, xJobRecycled; size_t xFreeHeapBeforeCreatingJob = xPortGetFreeHeapSize(), xFreeHeapAfterCreatingJob = 0; IotTaskPoolJobStatus_t xJobStatus; /* Don't expect any notifications to be pending yet. */ configASSERT( ulTaskNotifyTake( pdTRUE, xNoDelay ) == 0 ); /* Create a recycleable 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 job's callback function. 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. */ xResult = IotTaskPool_CreateRecyclableJob( NULL, prvSimpleTaskNotifyCallback, (void * ) xTaskGetCurrentTaskHandle(), &( xJob ) ); configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); /* The job is 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. So * expect there to be less heap space than when entering the function. */ xFreeHeapAfterCreatingJob = xPortGetFreeHeapSize(); configASSERT( xFreeHeapAfterCreatingJob < xFreeHeapBeforeCreatingJob ); /* The job has been created but not scheduled so is now ready. */ IotTaskPool_GetStatus( NULL, xJob, &xJobStatus ); configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_READY ); /* 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. */ xResult = IotTaskPool_Schedule( NULL, xJob, ulNoFlags ); configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); /* 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. */ xNoDelay ); /* No block time, return immediately. */ configASSERT( ulNotificationValue == 1 ); /* The job's callback has executed so the job is now completed. */ IotTaskPool_GetStatus( NULL, xJob, &xJobStatus ); configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_COMPLETED ); /* Return the job to the task pool's job cache. */ IotTaskPool_RecycleJob( NULL, xJob ); /* Create a recycleable job again using the handle of this task as the job's * context and the function that sends a notification to the task handle as * the job's callback function. 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. */ xResult = IotTaskPool_CreateRecyclableJob( NULL, prvSimpleTaskNotifyCallback, (void * ) xTaskGetCurrentTaskHandle(), &( xJobRecycled ) ); configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); /* Since this time the task pool's job cache had a recycleable job, it must * have been re-used. Thefore expect the free heap space to be same as after * the creation of first job */ configASSERT( xPortGetFreeHeapSize() == xFreeHeapAfterCreatingJob ); /* Expect the task pool to re-use the job in its cache as opposed to * allocating a new one. */ configASSERT( xJobRecycled == 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. */ xResult = IotTaskPool_Schedule( NULL, xJobRecycled, ulNoFlags ); configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); /* 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. */ xNoDelay ); /* No block time, return immediately. */ configASSERT( ulNotificationValue == 2 ); /* The job's callback has executed so the job is now completed. */ IotTaskPool_GetStatus( NULL, xJobRecycled, &xJobStatus ); configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_COMPLETED ); /* Clean up 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. */ xResult = IotTaskPool_DestroyRecyclableJob( NULL, xJobRecycled ); configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); /* Clear all the notification value bits ready for the next example. */ xTaskNotifyWait( portMAX_DELAY, /* Clear all bits on entry - portMAX_DELAY is used as it is a portable way of having all bits set. */ 0UL, /* Don't clear any bits on exit. */ NULL, /* Don't need the notification value this time. */ xNoDelay ); /* No block time, return immediately. */ configASSERT( ulTaskNotifyTake( pdTRUE, xNoDelay ) == 0 ); /* Once the job has been deleted the memory used to hold the job is * returned, so the available heap should be exactly as when entering this * function. */ configASSERT( xPortGetFreeHeapSize() == xFreeHeapBeforeCreatingJob ); } /*-----------------------------------------------------------*/ static void prvExample_ReuseRecyclableJobFromHighPriorityTask( void ) { IotTaskPoolError_t xResult; uint32_t ulNotificationValue; const uint32_t ulNoFlags = 0UL; const TickType_t xNoDelay = ( TickType_t ) 0; TickType_t xShortDelay = pdMS_TO_TICKS( 150 ); IotTaskPoolJob_t xJob, xJobRecycled; size_t xFreeHeapBeforeCreatingJob = xPortGetFreeHeapSize(), xFreeHeapAfterCreatingJob = 0; IotTaskPoolJobStatus_t xJobStatus; /* Don't expect any notifications to be pending yet. */ configASSERT( ulTaskNotifyTake( pdTRUE, xNoDelay ) == 0 ); /* prvExample_ReuseRecyclableJobFromLowPriorityTask() executes in a task * that has a lower [task] priority than the task pool's worker tasks. * Therefore a task 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 a recycleable 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 job's callback function. 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. */ xResult = IotTaskPool_CreateRecyclableJob( NULL, prvSimpleTaskNotifyCallback, (void * ) xTaskGetCurrentTaskHandle(), &( xJob ) ); configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); /* The job is 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. So * expect there to be less heap space than when entering the function. */ xFreeHeapAfterCreatingJob = xPortGetFreeHeapSize(); configASSERT( xFreeHeapAfterCreatingJob < xFreeHeapBeforeCreatingJob ); /* The job has been created but not scheduled so is now ready. */ IotTaskPool_GetStatus( NULL, xJob, &xJobStatus ); configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_READY ); /* 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. */ xResult = IotTaskPool_Schedule( NULL, xJob, ulNoFlags ); configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); /* 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 * yet, 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. */ xNoDelay ); /* No block time, return immediately. */ configASSERT( ulNotificationValue == 0 ); /* When this task blocks to wait for a notification, a worker thread will be * able to execute - 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 expects to receive one notification. */ 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 == 1 ); /* Since the scheduled job has 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 == 1 ); /* The job's callback has executed so the job is now completed. */ IotTaskPool_GetStatus( NULL, xJob, &xJobStatus ); configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_COMPLETED ); /* Return the job to the task pool's job cache. */ IotTaskPool_RecycleJob( NULL, xJob ); /* Create a recycleable job again using the handle of this task as the job's * context and the function that sends a notification to the task handle as * the job's callback function. 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. */ xResult = IotTaskPool_CreateRecyclableJob( NULL, prvSimpleTaskNotifyCallback, (void * ) xTaskGetCurrentTaskHandle(), &( xJobRecycled ) ); configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); /* Since this time the task pool's job cache had a recycleable job, it must * have been re-used. Thefore expect the free heap space to be same as after * the creation of first job */ configASSERT( xPortGetFreeHeapSize() == xFreeHeapAfterCreatingJob ); /* Expect the task pool to re-use the job in its cache as opposed to * allocating a new one. */ configASSERT( xJobRecycled == 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. */ xResult = IotTaskPool_Schedule( NULL, xJobRecycled, ulNoFlags ); configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); /* 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 * yet, 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. */ xNoDelay ); /* No block time, return immediately. */ configASSERT( ulNotificationValue == 1 ); /* When this task blocks to wait for a notification, a worker thread will be * able to execute - 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 expects to receive one notification. */ 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 == 2 ); /* Since the scheduled job has 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 == 2 ); /* The job's callback has executed so the job is now completed. */ IotTaskPool_GetStatus( NULL, xJobRecycled, &xJobStatus ); configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_COMPLETED ); /* Clean up 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. */ xResult = IotTaskPool_DestroyRecyclableJob( NULL, xJobRecycled ); configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); /* Reset this task's priority. */ vTaskPrioritySet( NULL, tskIDLE_PRIORITY ); /* Clear all the notification value bits ready for the next example. */ xTaskNotifyWait( portMAX_DELAY, /* Clear all bits on entry - portMAX_DELAY is used as it is a portable way of having all bits set. */ 0UL, /* Don't clear any bits on exit. */ NULL, /* Don't need the notification value this time. */ xNoDelay ); /* No block time, return immediately. */ configASSERT( ulTaskNotifyTake( pdTRUE, xNoDelay ) == 0 ); /* Once the job has been deleted the memory used to hold the job is * returned, so the available heap should be exactly as when entering this * function. */ configASSERT( xPortGetFreeHeapSize() == xFreeHeapBeforeCreatingJob ); } /*-----------------------------------------------------------*/