From 2ec12259a4757b7f43d6901e10ddbe535a59e913 Mon Sep 17 00:00:00 2001 From: gaurav-aws Date: Fri, 19 Jul 2019 00:02:45 +0000 Subject: [PATCH] Update the task pool demo to show re-use of recyclable jobs The example now creates a recyclable job, schedules it and returns it back to the task pool when it is done. It then again creates a recyclable job and ensures that the task pool the same job present it its cache. git-svn-id: https://svn.code.sf.net/p/freertos/code/trunk@2687 1d2547de-c912-0410-9cb9-b8ca96c0e9e2 --- .../DemoTasks/SimpleTaskPoolExamples.c | 629 ++++++++++-------- 1 file changed, 363 insertions(+), 266 deletions(-) diff --git a/FreeRTOS-Plus/Demo/FreeRTOS_IoT_Libraries/task_pool/DemoTasks/SimpleTaskPoolExamples.c b/FreeRTOS-Plus/Demo/FreeRTOS_IoT_Libraries/task_pool/DemoTasks/SimpleTaskPoolExamples.c index 49924537e..e7fb1e070 100644 --- a/FreeRTOS-Plus/Demo/FreeRTOS_IoT_Libraries/task_pool/DemoTasks/SimpleTaskPoolExamples.c +++ b/FreeRTOS-Plus/Demo/FreeRTOS_IoT_Libraries/task_pool/DemoTasks/SimpleTaskPoolExamples.c @@ -41,10 +41,6 @@ created. */ #define tpTASK_POOL_WORKER_PRIORITY 1 -/* The number of jobs created in the example functions that create more than -one job. */ -#define tpJOBS_TO_CREATE 5 - /* * Prototypes for the functions that demonstrate the task pool API. * See the implementation of the prvTaskPoolDemoTask() function within this file @@ -75,27 +71,27 @@ 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. */ + * 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. */ + * 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. */ + * 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. */ + * 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, @@ -106,13 +102,13 @@ static const IotTaskPoolInfo_t xTaskPoolParameters = { void vStartSimpleTaskPoolDemo( void ) { /* This example uses a single application task, which in turn is used to - create and send jobs to task pool tasks. */ + * 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 tsak - not used in this case. */ + NULL ); /* Used to pass out a handle to the created task - not used in this case. */ } /*-----------------------------------------------------------*/ @@ -125,49 +121,49 @@ uint32_t ulLoops = 0; ( 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. */ + * 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. */ + * (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. */ + * 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. */ + * 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. */ + * 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 multiple recyclable jobs 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. */ + /* 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 multiple recyclable jobs being used, but 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 enteres the blocked - state. */ + /* 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++; @@ -183,7 +179,7 @@ uint32_t ulLoops = 0; 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. */ + * be sent. */ TaskHandle_t xTaskToNotify = ( TaskHandle_t ) pUserContext; /* Remove warnings about unused parameters. */ @@ -207,15 +203,15 @@ size_t xFreeHeapBeforeCreatingJob = xPortGetFreeHeapSize(); IotTaskPoolJobStatus_t xJobStatus; /* Don't expect any notifications to be pending yet. */ - configASSERT( ulTaskNotifyTake( pdTRUE, 0 ) == 0 ); + 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 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. */ + * 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, @@ -227,22 +223,22 @@ IotTaskPoolJobStatus_t 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 chanced since entering this function. */ + * 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. */ + * 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 pre-empts this task and sends the notification (from the job's - callback) as soon as the job is scheduled. */ + * 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 ); @@ -265,12 +261,12 @@ size_t xFreeHeapBeforeCreatingJob = xPortGetFreeHeapSize(); IotTaskPoolJobStatus_t xJobStatus; /* Don't expect any notifications to be pending yet. */ - configASSERT( ulTaskNotifyTake( pdTRUE, 0 ) == 0 ); + 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 jobs callback - function. The job is created using storage allocated on the stack of this - function - so no memory is allocated. */ + * 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, @@ -282,49 +278,49 @@ IotTaskPoolJobStatus_t 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 chanced since entering this function. */ + * 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 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. */ + /* 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'. */ + * 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 stopped. */ + /* 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. */ + * 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. */ + * 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... */ + /* 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. */ + * 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 ) ) ); } @@ -340,19 +336,19 @@ const TickType_t xNoDelay = ( TickType_t ) 0; size_t xFreeHeapBeforeCreatingJob = xPortGetFreeHeapSize(); /* Don't expect any notifications to be pending yet. */ - configASSERT( ulTaskNotifyTake( pdTRUE, 0 ) == 0 ); + 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 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. */ + * 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(), @@ -360,34 +356,34 @@ size_t xFreeHeapBeforeCreatingJob = xPortGetFreeHeapSize(); configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); /* This recyclable job is persistent, and in this case created dynamically, - so expect there to be less heap space then when entering the function. */ + * 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. */ + * 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 pre-empts this task and sends the notification (from the job's - callback) as soon as the job is scheduled. */ + * 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. */ + * 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. */ + * returned, so the available heap should be exactly as when entering this + * function. */ configASSERT( xPortGetFreeHeapSize() == xFreeHeapBeforeCreatingJob ); } /*-----------------------------------------------------------*/ @@ -395,106 +391,127 @@ size_t xFreeHeapBeforeCreatingJob = xPortGetFreeHeapSize(); static void prvExample_ReuseRecyclableJobFromLowPriorityTask( void ) { IotTaskPoolError_t xResult; -uint32_t x, xIndex, ulNotificationValue; +uint32_t ulNotificationValue; const uint32_t ulNoFlags = 0UL; -IotTaskPoolJob_t xJobs[ tpJOBS_TO_CREATE ]; -size_t xFreeHeapBeforeCreatingJob = xPortGetFreeHeapSize(); +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, 0 ) == 0 ); - - /* 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++ ) - { - xResult = IotTaskPool_CreateRecyclableJob( NULL, - prvSimpleTaskNotifyCallback, - (void * ) xTaskGetCurrentTaskHandle(), - &( xJobs[ x ] ) ); - configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); - - /* The job has been created but not scheduled so is now ready. */ - IotTaskPool_GetStatus( NULL, xJobs[ x ], &xJobStatus ); - configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_READY ); - } + 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 ); - /* 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; - - xResult = IotTaskPool_Schedule( NULL, xJobs[ xIndex ], 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. */ - 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. *//*_RB_ Why not recycle it automatically? */ - IotTaskPool_RecycleJob( NULL, xJobs[ xIndex ] ); - xResult = IotTaskPool_CreateRecyclableJob( NULL, - prvSimpleTaskNotifyCallback, - (void * ) xTaskGetCurrentTaskHandle(), - &( xJobs[ xIndex ] ) ); - 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 ); - /* Clear all the notification value bits again. */ + /* 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. */ - 0UL ); /* No block time, return immediately. */ - configASSERT( ulTaskNotifyTake( pdTRUE, 0 ) == 0 ); - - /* 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++ ) - { - xResult = IotTaskPool_DestroyRecyclableJob( NULL, xJobs[ x ] ); - configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); - } + 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. */ + * returned, so the available heap should be exactly as when entering this + * function. */ configASSERT( xPortGetFreeHeapSize() == xFreeHeapBeforeCreatingJob ); } /*-----------------------------------------------------------*/ @@ -502,98 +519,178 @@ IotTaskPoolJobStatus_t xJobStatus; static void prvExample_ReuseRecyclableJobFromHighPriorityTask( void ) { IotTaskPoolError_t xResult; -uint32_t x, ulNotificationValue; +uint32_t ulNotificationValue; const uint32_t ulNoFlags = 0UL; -IotTaskPoolJob_t xJobs[ tpJOBS_TO_CREATE ]; -IotTaskPoolJobStorage_t xJobStorage[ tpJOBS_TO_CREATE ]; -size_t xFreeHeapBeforeCreatingJob = xPortGetFreeHeapSize(); +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, 0 ) == 0 ); + 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 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. */ + * 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 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++ ) - { - xResult = IotTaskPool_CreateJob( prvSimpleTaskNotifyCallback, /* Callback function. */ - ( void * ) xTaskGetCurrentTaskHandle(), /* Job context. */ - &( xJobStorage[ x ] ), - &( xJobs[ x ] ) ); - configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); - - /* 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 chanced since entering this function. */ - configASSERT( xFreeHeapBeforeCreatingJob == xPortGetFreeHeapSize() ); - } + /* 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 ); - for( x = 0; x < tpJOBS_TO_CREATE; x++ ) - { - /* Schedule the next job. */ - xResult = IotTaskPool_Schedule( NULL, xJobs[ x ], ulNoFlags ); - configASSERT( xResult == IOT_TASKPOOL_SUCCESS ); - - /* 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 ); - } + /* 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 ); - /* 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 ); /* Short delay to allow a task pool worker to execute. */ - configASSERT( ulNotificationValue == ( x + 1 ) ); - } + /* 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 ); - /* All the scheduled jobs have now executed, so waiting for another - notification should timeout without the notification value changing. */ + /* 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 == x ); + configASSERT( ulNotificationValue == 2 ); - /* Reset the priority of this task and clear the notifications ready for the - next example. */ + /* 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. */ - 0UL ); /* No block time, return immediately. */ + 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 ); } /*-----------------------------------------------------------*/ - -- 2.39.5