git.sur5r.net Git - freertos/blob - FreeRTOS-Labs/Demo/FreeRTOS_IoT_Libraries/utilities/task_pool/DemoTasks/SimpleTaskPoolExamples.c

   1 /*\r
   2  * FreeRTOS Kernel V10.3.0\r
   3  * Copyright (C) 2020 Amazon.com, Inc. or its affiliates.  All Rights Reserved.\r
   4  *\r
   5  * Permission is hereby granted, free of charge, to any person obtaining a copy of\r
   6  * this software and associated documentation files (the "Software"), to deal in\r
   7  * the Software without restriction, including without limitation the rights to\r
   8  * use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of\r
   9  * the Software, and to permit persons to whom the Software is furnished to do so,\r
  10  * subject to the following conditions:\r
  11  *\r
  12  * The above copyright notice and this permission notice shall be included in all\r
  13  * copies or substantial portions of the Software.\r
  14  *\r
  15  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\r
  16  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS\r
  17  * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR\r
  18  * COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER\r
  19  * IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\r
  20  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r
  21  *\r
  22  * http://www.FreeRTOS.org\r
  23  * http://aws.amazon.com/freertos\r
  24  *\r
  25  * 1 tab == 4 spaces!\r
  26  */\r
  27 \r
  28 \r
  29 /* Kernel includes. */\r
  30 #include "FreeRTOS.h"\r
  31 #include "task.h"\r
  32 \r
  33 /* Standard includes. */\r
  34 #include <stdio.h>\r
  35 \r
  36 /* IoT SDK includes. */\r
  37 #include "iot_taskpool_freertos.h"\r
  38 \r
  39 /* Demo includes. */\r
  40 #include "demo_config.h"\r
  41 \r
  42 /* The priority at which that tasks in the task pool (the worker tasks) get\r
  43 created. */\r
  44 #define tpTASK_POOL_WORKER_PRIORITY             1\r
  45 \r
  46 /*\r
  47  * Prototypes for the functions that demonstrate the task pool API.\r
  48  * See the implementation of the prvTaskPoolDemoTask() function within this file\r
  49  * for a description of the individual functions.  A configASSERT() is hit if\r
  50  * any of the demos encounter any unexpected behavior.\r
  51  */\r
  52 static void prvExample_BasicSingleJob( void );\r
  53 static void prvExample_DeferredJobAndCancellingJobs( void );\r
  54 \r
  55 /*\r
  56  * Prototypes of the callback functions used in the examples.  The callback\r
  57  * simply sends a signal (in the form of a direct task notification) to the\r
  58  * prvTaskPoolDemoTask() task to let the task know that the callback execute.\r
  59  * The handle of the prvTaskPoolDemoTask() task is not accessed directly, but\r
  60  * instead passed into the task pool job as the job's context.\r
  61  */\r
  62 static void prvSimpleTaskNotifyCallback( IotTaskPool_t pTaskPool, IotTaskPoolJob_t pJob, void *pUserContext );\r
  63 \r
  64 /*\r
  65  * The task used to demonstrate the task pool API.  This task just loops through\r
  66  * each demo in turn.\r
  67  */\r
  68 static void prvTaskPoolDemoTask( void *pvParameters );\r
  69 \r
  70 /*-----------------------------------------------------------*/\r
  71 \r
  72 /* Parameters used to create the system task pool - see TBD for more information\r
  73  * as the task pool used in this example is a slimmed down version of the full\r
  74  * library - the slimmed down version being intended specifically for FreeRTOS\r
  75  * kernel use cases. */\r
  76 static const IotTaskPoolInfo_t xTaskPoolParameters = {\r
  77                                                                                                                 /* minThreads:\r
  78                                                                                                                  * Minimum number of threads in a task pool.\r
  79                                                                                                                  * Note the slimmed down version of the task\r
  80                                                                                                                  * pool used by this library does not auto-scale\r
  81                                                                                                                  * the number of tasks in the pool so in this\r
  82                                                                                                                  * case this sets the number of tasks in the\r
  83                                                                                                                  * pool. */\r
  84                                                                                                                 IOT_TASKPOOL_NUMBER_OF_WORKERS,\r
  85                                                                                                                 /* maxThreads:\r
  86                                                                                                                  * Maximum number of threads in a task pool.\r
  87                                                                                                                  * Note the slimmed down version of the task\r
  88                                                                                                                  * pool used by this library does not auto-scale\r
  89                                                                                                                  * the number of tasks in the pool so in this\r
  90                                                                                                                  * case this parameter must match minThreads. */\r
  91                                                                                                                 IOT_TASKPOOL_NUMBER_OF_WORKERS,\r
  92                                                                                                                 /* Stack size for every task pool thread - in\r
  93                                                                                                                  * bytes, hence multiplying by the number of bytes\r
  94                                                                                                                  * in a word as configMINIMAL_STACK_SIZE is\r
  95                                                                                                                  * specified in words. */\r
  96                                                                                                                 configMINIMAL_STACK_SIZE * sizeof( portSTACK_TYPE ),\r
  97                                                                                                                 /* Priority for every task pool thread. */\r
  98                                                                                                                 tpTASK_POOL_WORKER_PRIORITY,\r
  99                                                                                                          };\r
 100 \r
 101 /*-----------------------------------------------------------*/\r
 102 \r
 103 void vStartSimpleTaskPoolDemo( void )\r
 104 {\r
 105         /* This example uses a single application task, which in turn is used to\r
 106          * create and send jobs to task pool tasks. */\r
 107         xTaskCreate( prvTaskPoolDemoTask,               /* Function that implements the task. */\r
 108                                  "PoolDemo",                            /* Text name for the task - only used for debugging. */\r
 109                                  democonfigDEMO_STACKSIZE,      /* Size of stack (in words, not bytes) to allocate for the task. */\r
 110                                  NULL,                                          /* Task parameter - not used in this case. */\r
 111                                  tskIDLE_PRIORITY,                      /* Task priority, must be between 0 and configMAX_PRIORITIES - 1. */\r
 112                                  NULL );                                        /* Used to pass out a handle to the created task - not used in this case. */\r
 113 }\r
 114 /*-----------------------------------------------------------*/\r
 115 \r
 116 static void prvTaskPoolDemoTask( void *pvParameters )\r
 117 {\r
 118 IotTaskPoolError_t xResult;\r
 119 uint32_t ulLoops = 0;\r
 120 \r
 121         /* Remove compiler warnings about unused parameters. */\r
 122         ( void ) pvParameters;\r
 123 \r
 124         configPRINTF( ( "---------STARTING DEMO---------\r\n" ) );\r
 125 \r
 126         /* The task pool must be created before it can be used.  The system task\r
 127          * pool is the task pool managed by the task pool library itself - the storage\r
 128          * used by the task pool is provided by the library. */\r
 129         xResult = IotTaskPool_CreateSystemTaskPool( &xTaskPoolParameters );\r
 130         configASSERT( xResult == IOT_TASKPOOL_SUCCESS );\r
 131 \r
 132         for( ;; )\r
 133         {\r
 134                 /* Demonstrate the most basic use case where a non persistent job is\r
 135                  * created and scheduled to run immediately.  The task pool worker tasks\r
 136                  * (in which the job callback function executes) have a priority above the\r
 137                  * priority of this task so the job's callback executes as soon as it is\r
 138                  * scheduled. */\r
 139                 prvExample_BasicSingleJob();\r
 140 \r
 141                 /* Demonstrate a job being scheduled to run at some time in the\r
 142                  * future, and how a job scheduled to run in the future can be canceled\r
 143                  * if it has not yet started executing.  */\r
 144                 prvExample_DeferredJobAndCancellingJobs();\r
 145 \r
 146                 ulLoops++;\r
 147                 if( ( ulLoops % 10UL ) == 0 )\r
 148                 {\r
 149                         configPRINTF( ( "prvTaskPoolDemoTask() performed %u iterations successfully.\r\n", ulLoops ) );\r
 150                         configPRINTF( ( "Demo completed successfully.\r\n" ) );\r
 151                         fflush( stdout );\r
 152                 }\r
 153         }\r
 154 }\r
 155 /*-----------------------------------------------------------*/\r
 156 \r
 157 static void prvSimpleTaskNotifyCallback( IotTaskPool_t pTaskPool, IotTaskPoolJob_t pJob, void *pUserContext )\r
 158 {\r
 159 /* The jobs context is the handle of the task to which a notification should\r
 160  * be sent. */\r
 161 TaskHandle_t xTaskToNotify = ( TaskHandle_t ) pUserContext;\r
 162 \r
 163         /* Remove warnings about unused parameters. */\r
 164         ( void ) pTaskPool;\r
 165         ( void ) pJob;\r
 166 \r
 167         /* Notify the task that created this job. */\r
 168         xTaskNotifyGive( xTaskToNotify );\r
 169 }\r
 170 /*-----------------------------------------------------------*/\r
 171 \r
 172 static void prvExample_BasicSingleJob( void )\r
 173 {\r
 174 IotTaskPoolJobStorage_t xJobStorage;\r
 175 IotTaskPoolJob_t xJob;\r
 176 IotTaskPoolError_t xResult;\r
 177 uint32_t ulReturn;\r
 178 const uint32_t ulNoFlags = 0UL;\r
 179 const TickType_t xNoDelay = ( TickType_t ) 0;\r
 180 size_t xFreeHeapBeforeCreatingJob = xPortGetFreeHeapSize();\r
 181 IotTaskPoolJobStatus_t xJobStatus;\r
 182 \r
 183         /* Direct to task notifications are used to communicate between worker tasks\r
 184         and this task.  Don't expect any notifications to be pending before commencing. */\r
 185         configASSERT( ulTaskNotifyTake( pdTRUE, xNoDelay ) == 0 );\r
 186 \r
 187         /* Create and schedule a job using the handle of this task as the job's\r
 188          * context and the function that sends a notification to the task handle as\r
 189          * the job's callback function.  This is not a recyclable job so the storage\r
 190          * required to hold information about the job is provided by this task - in\r
 191          * this case the storage is on the stack of this task so no memory is allocated\r
 192          * dynamically but the stack frame must remain in scope for the lifetime of\r
 193          * the job. */\r
 194         xResult = IotTaskPool_CreateJob(  prvSimpleTaskNotifyCallback, /* Callback function. */\r
 195                                                                           ( void * ) xTaskGetCurrentTaskHandle(), /* Job context. */\r
 196                                                                           &xJobStorage,\r
 197                                                                           &xJob );\r
 198         configASSERT( xResult == IOT_TASKPOOL_SUCCESS );\r
 199 \r
 200         /* The job has been created but not scheduled so is now ready. */\r
 201         IotTaskPool_GetStatus( NULL, xJob, &xJobStatus );\r
 202         configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_READY );\r
 203 \r
 204         /* This is not a persistent (recyclable) job and its storage is on the\r
 205          * stack of this function, so the amount of heap space available should not\r
 206          * have changed since entering this function. */\r
 207         configASSERT( xFreeHeapBeforeCreatingJob == xPortGetFreeHeapSize() );\r
 208 \r
 209         /* In the full task pool implementation the first parameter is used to\r
 210          * pass the handle of the task pool to schedule.  The lean task pool\r
 211          * implementation used in this demo only supports a single task pool, which\r
 212          * is created internally within the library, so the first parameter is NULL. */\r
 213         xResult = IotTaskPool_Schedule( NULL, xJob, ulNoFlags );\r
 214         configASSERT( xResult == IOT_TASKPOOL_SUCCESS );\r
 215 \r
 216         /* Look for the notification coming from the job's callback function.  The\r
 217          * priority of the task pool worker task that executes the callback is higher\r
 218          * than the priority of this task so a block time is not needed - the task pool\r
 219          * worker task preempts this task and sends the notification (from the job's\r
 220          * callback) as soon as the job is scheduled. */\r
 221         ulReturn = ulTaskNotifyTake( pdTRUE, xNoDelay );\r
 222         configASSERT( ulReturn );\r
 223 \r
 224         /* The job's callback has executed so the job has now completed. */\r
 225         IotTaskPool_GetStatus( NULL, xJob, &xJobStatus );\r
 226         configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_COMPLETED );\r
 227 }\r
 228 /*-----------------------------------------------------------*/\r
 229 \r
 230 static void prvExample_DeferredJobAndCancellingJobs( void )\r
 231 {\r
 232 IotTaskPoolJobStorage_t xJobStorage;\r
 233 IotTaskPoolJob_t xJob;\r
 234 IotTaskPoolError_t xResult;\r
 235 uint32_t ulReturn;\r
 236 const uint32_t ulShortDelay_ms = 100UL;\r
 237 const TickType_t xNoDelay = ( TickType_t ) 0, xAllowableMargin = ( TickType_t ) 5; /* Large margin for Windows port, which is not real time. */\r
 238 TickType_t xTimeBefore, xElapsedTime, xShortDelay_ticks;\r
 239 size_t xFreeHeapBeforeCreatingJob = xPortGetFreeHeapSize();\r
 240 IotTaskPoolJobStatus_t xJobStatus;\r
 241 \r
 242         /* Don't expect any notifications to be pending yet. */\r
 243         configASSERT( ulTaskNotifyTake( pdTRUE, xNoDelay ) == 0 );\r
 244 \r
 245         /* Create a job using the handle of this task as the job's context and the\r
 246          * function that sends a notification to the task handle as the job's callback\r
 247          * function.  The job is created using storage allocated on the stack of this\r
 248          * function - so no memory is allocated. */\r
 249         xResult = IotTaskPool_CreateJob(  prvSimpleTaskNotifyCallback, /* Callback function. */\r
 250                                                                           ( void * ) xTaskGetCurrentTaskHandle(), /* Job context. */\r
 251                                                                           &xJobStorage,\r
 252                                                                           &xJob );\r
 253         configASSERT( xResult == IOT_TASKPOOL_SUCCESS );\r
 254 \r
 255         /* The job has been created but not scheduled so is now ready. */\r
 256         IotTaskPool_GetStatus( NULL, xJob, &xJobStatus );\r
 257         configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_READY );\r
 258 \r
 259         /* This is not a persistent (recyclable) job and its storage is on the\r
 260          * stack of this function, so the amount of heap space available should not\r
 261          * have changed since entering this function. */\r
 262         configASSERT( xFreeHeapBeforeCreatingJob == xPortGetFreeHeapSize() );\r
 263 \r
 264         /* Schedule the job to run its callback in ulShortDelay_ms milliseconds time.\r
 265          * In the full task pool implementation the first parameter is used to  pass the\r
 266          * handle of the task pool to schedule.  The lean task pool implementation used\r
 267          * in this demo only supports a single task pool, which is created internally\r
 268          * within the library, so the first parameter is NULL. */\r
 269         xResult = IotTaskPool_ScheduleDeferred( NULL, xJob, ulShortDelay_ms );\r
 270         configASSERT( xResult == IOT_TASKPOOL_SUCCESS );\r
 271 \r
 272         /* The scheduled job should not have executed yet, so don't expect any\r
 273          * notifications and expect the job's status to be 'deferred'. */\r
 274         ulReturn = ulTaskNotifyTake( pdTRUE, xNoDelay );\r
 275         configASSERT( ulReturn == 0 );\r
 276         IotTaskPool_GetStatus( NULL, xJob, &xJobStatus );\r
 277         configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_DEFERRED );\r
 278 \r
 279         /* As the job has not yet been executed it can be canceled. */\r
 280         xResult = IotTaskPool_TryCancel( NULL, xJob, &xJobStatus );\r
 281         configASSERT( xResult == IOT_TASKPOOL_SUCCESS );\r
 282         IotTaskPool_GetStatus( NULL, xJob, &xJobStatus );\r
 283         configASSERT( xJobStatus == IOT_TASKPOOL_STATUS_CANCELED );\r
 284 \r
 285         /* Schedule the job again, and this time wait until its callback is\r
 286          * executed (the callback function sends a notification to this task) to see\r
 287          * that it executes at the right time. */\r
 288         xTimeBefore = xTaskGetTickCount();\r
 289         xResult = IotTaskPool_ScheduleDeferred( NULL, xJob, ulShortDelay_ms );\r
 290         configASSERT( xResult == IOT_TASKPOOL_SUCCESS );\r
 291 \r
 292         /* Wait twice the deferred execution time to ensure the callback is executed\r
 293          * before the call below times out. */\r
 294         ulReturn = ulTaskNotifyTake( pdTRUE, pdMS_TO_TICKS( ulShortDelay_ms * 2UL ) );\r
 295         xElapsedTime = xTaskGetTickCount() - xTimeBefore;\r
 296 \r
 297         /* A single notification should have been received... */\r
 298         configASSERT( ulReturn == 1 );\r
 299 \r
 300         /* ...and the time since scheduling the job should be greater than or\r
 301          * equal to the deferred execution time - which is converted to ticks for\r
 302          * comparison. */\r
 303         xShortDelay_ticks = pdMS_TO_TICKS( ulShortDelay_ms );\r
 304         configASSERT( ( xElapsedTime >= xShortDelay_ticks ) && ( xElapsedTime  < ( xShortDelay_ticks + xAllowableMargin ) ) );\r
 305 }\r
 306 /*-----------------------------------------------------------*/\r