Remove IotTaskPool_CreateRecyclableSystemJob() and IotTaskPool_ScheduleSystemJob() again, which were intended to be alternative APIs that only access the system task pool, and instead update IotTaskPool_CreateRecyclableJob() and IotTaskPool_ScheduleJob() to allow the parameter used to pass in the task pool handle to be NULL if the system task pool is the only one available.

Update the task pool demo app to include a lot more functionality.

git-svn-id: http://svn.code.sf.net/p/freertos/code/trunk@2674 1d2547de-c912-0410-9cb9-b8ca96c0e9e2

2 files changed, 79 insertions, 162 deletions

diff --git a/FreeRTOS-Plus/Source/FreeRTOS-Plus-IoT-SDK/c_sdk/standard/common/include/iot_taskpool.h b/FreeRTOS-Plus/Source/FreeRTOS-Plus-IoT-SDK/c_sdk/standard/common/include/iot_taskpool.h
index 7e94e7264..a91ccf152 100644
--- a/FreeRTOS-Plus/Source/FreeRTOS-Plus-IoT-SDK/c_sdk/standard/common/include/iot_taskpool.h
+++ b/FreeRTOS-Plus/Source/FreeRTOS-Plus-IoT-SDK/c_sdk/standard/common/include/iot_taskpool.h
@@ -53,11 +53,9 @@
  * - @functionname{taskpool_function_setmaxthreads}

  * - @functionname{taskpool_function_createjob}

  * - @functionname{taskpool_function_createrecyclablejob}

- * - @functionname{taskpool_function_createrecyclablesystemjob}

  * - @functionname{taskpool_function_destroyrecyclablejob}

  * - @functionname{taskpool_function_recyclejob}

  * - @functionname{taskpool_function_schedule}

- * - @functionname{taskpool_function_schedulesystemjob}

  * - @functionname{taskpool_function_scheduledeferred}

  * - @functionname{taskpool_function_getstatus}

  * - @functionname{taskpool_function_trycancel}

@@ -73,11 +71,9 @@
  * @functionpage{IotTaskPool_SetMaxThreads,taskpool,setmaxthreads}

  * @functionpage{IotTaskPool_CreateJob,taskpool,createjob}

  * @functionpage{IotTaskPool_CreateRecyclableJob,taskpool,createrecyclablejob}

- * @functionpage{IotTaskPool_CreateRecyclableSystemJob,taskpool,createrecyclablesystemjob}

  * @functionpage{IotTaskPool_DestroyRecyclableJob,taskpool,destroyrecyclablejob}

  * @functionpage{IotTaskPool_RecycleJob,taskpool,recyclejob}

  * @functionpage{IotTaskPool_Schedule,taskpool,schedule}

- * @functionpage{IotTaskPool_ScheduleSystemJob,taskpool,schedule}

  * @functionpage{IotTaskPool_ScheduleDeferred,taskpool,scheduledeferred}

  * @functionpage{IotTaskPool_GetStatus,taskpool,getstatus}

  * @functionpage{IotTaskPool_TryCancel,taskpool,trycancel}

@@ -164,7 +160,7 @@ IotTaskPoolError_t IotTaskPool_Create( const IotTaskPoolInfo_t * const pInfo,
  * This function should be called to destroy one instance of a task pool previously created with a call

  * to @ref IotTaskPool_Create or @ref IotTaskPool_CreateSystemTaskPool.

  * Calling this fuction release all underlying resources. After calling this function, any job scheduled but not yet executed

- * will be cancelled and destroyed.

+ * will be canceled and destroyed.

  * The `taskPool` instance will no longer be valid after this function returns.

  *

  * @param[in] taskPool A handle to the task pool, e.g. as returned by a call to @ref IotTaskPool_Create or

@@ -247,7 +243,7 @@ IotTaskPoolError_t IotTaskPool_CreateJob( IotTaskPoolRoutine_t userCallback,
  * - #IOT_TASKPOOL_NO_MEMORY

  * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS

  *

- * @note This function will not allocate memory.

+ * @note This function will not allocate memory. //_RB_ Incorrect comment.

  *

  * @warning A recyclable job should be recycled with a call to @ref IotTaskPool_RecycleJob rather than destroyed.

  *

@@ -260,36 +256,6 @@ IotTaskPoolError_t IotTaskPool_CreateRecyclableJob( IotTaskPool_t taskPool,
 /* @[declare_taskpool_createrecyclablejob] */

 

 /**

- * brief Creates a job for the system task pool by allocating the job dynamically.

- * The system task pool is the task pool created by @ref IotTaskPool_CreateSystemTaskPool.

- *

- * A recyclable job does not need to be allocated twice, but it can rather be reused through

- * subsequent calls to @ref IotTaskPool_CreateRecyclableJob.

- *

- * @param[in] userCallback A user-specified callback for the job.

- * @param[in] pUserContext A user-specified context for the callback.

- * @param[out] pJob A pointer to an instance of @ref IotTaskPoolJob_t that will be initialized when this

- * function returns successfully. This handle can be used to inspect the job status with

- * @ref IotTaskPool_GetStatus or cancel the job with @ref IotTaskPool_TryCancel, etc....

- *

- * @return One of the following:

- * - #IOT_TASKPOOL_SUCCESS

- * - #IOT_TASKPOOL_BAD_PARAMETER

- * - #IOT_TASKPOOL_NO_MEMORY

- * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS

- *

- * @note This function will not allocate memory.

- *

- * @warning A recyclable job should be recycled with a call to @ref IotTaskPool_RecycleJob rather than destroyed.

- *

- */

-/* @[declare_taskpool_createrecyclablesystemjob] */

-IotTaskPoolError_t IotTaskPool_CreateRecyclableSystemJob( IotTaskPoolRoutine_t userCallback,

-                                                          void * pUserContext,

-                                                          IotTaskPoolJob_t * const pJob );

-/* @[declare_taskpool_createrecyclablesystemjob] */

-

-/**

  * @brief This function un-initializes a job.

  *

  * This function will destroy a job created with @ref IotTaskPool_CreateRecyclableJob.

@@ -445,88 +411,7 @@ IotTaskPoolError_t IotTaskPool_RecycleJob( IotTaskPool_t taskPool,
 IotTaskPoolError_t IotTaskPool_Schedule( IotTaskPool_t taskPool,

                                          IotTaskPoolJob_t job,

                                          uint32_t flags );

-

-/**

- * @brief This function schedules a job created with @ref IotTaskPool_CreateJob or @ref IotTaskPool_CreateRecyclableJob @ref IotTaskPool_CreateRecyclableSystemJob

- * against the system task pool.  The system task pool is the task pool created by @ref IotTaskPool_CreateSystemTaskPool.

- *

- * See @ref taskpool_design for a description of the jobs lifetime and interaction with the threads used in the task pool

- * library.

- *

- * @param[in] job A job to schedule for execution. This must be first initialized with a call to @ref IotTaskPool_CreateJob.

- * @param[in] flags Flags to be passed by the user, e.g. to identify the job as high priority by specifying #IOT_TASKPOOL_JOB_HIGH_PRIORITY.

- *

- * @return One of the following:

- * - #IOT_TASKPOOL_SUCCESS

- * - #IOT_TASKPOOL_BAD_PARAMETER

- * - #IOT_TASKPOOL_ILLEGAL_OPERATION

- * - #IOT_TASKPOOL_NO_MEMORY

- * - #IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS

- *

- *

- * @note This function will not allocate memory, so it is guaranteed to succeed if the parameters are correct and the task pool

- * was correctly initialized, and not yet destroyed.

- *

- * <b>Example</b>

- * @code{c}

- * // An example of a user context to pass to a callback through a task pool thread.

- * typedef struct JobUserContext

- * {

- *     uint32_t counter;

- * } JobUserContext_t;

- *

- * // An example of a user callback to invoke through a task pool thread.

- * static void ExecutionCb( IotTaskPool_t taskPool, IotTaskPoolJob_t job, void * context )

- * {

- *     ( void )taskPool;

- *     ( void )job;

- *

- *     JobUserContext_t * pUserContext = ( JobUserContext_t * )context;

- *

- *     pUserContext->counter++;

- * }

- *

- * void TaskPoolExample( )

- * {

- *     JobUserContext_t userContext = { 0 };

- *     IotTaskPoolJob_t job;

- *

- *     // Create the system task pool.  This example assumes the task pool is created successfully.

- *     // It is recommended to test the function's return value in production code.

- *     IotTaskPool_CreateSystemTaskPool( &xTaskPoolParameters );

- *

- *     // Statically allocate one job, schedule it.

- *     IotTaskPool_CreateJob( &ExecutionCb, &userContext, &job );

- *

- *     IotTaskPoolError_t errorSchedule = IotTaskPool_ScheduleSystemJob( &job, 0 );

- *

- *     switch ( errorSchedule )

- *     {

- *     case IOT_TASKPOOL_SUCCESS:

- *         break;

- *     case IOT_TASKPOOL_BAD_PARAMETER:          // Invalid parameters, such as a NULL handle, can trigger this error.

- *     case IOT_TASKPOOL_ILLEGAL_OPERATION:      // Scheduling a job that was previously scheduled or destroyed could trigger this error.

- *     case IOT_TASKPOOL_NO_MEMORY:              // Scheduling a with flag #IOT_TASKPOOL_JOB_HIGH_PRIORITY could trigger this error.

- *     case IOT_TASKPOOL_SHUTDOWN_IN_PROGRESS:   // Scheduling a job after trying to destroy the task pool could trigger this error.

- *         // ASSERT

- *         break;

- *     default:

- *         // ASSERT

- *     }

- *

- *     //

- *     // ... Perform other operations ...

- *     //

- *

- *     IotTaskPool_Destroy( taskPool );

- * }

- * @endcode

- */

-/* @[declare_taskpool_schedulesystemjob] */

-IotTaskPoolError_t IotTaskPool_ScheduleSystemJob( IotTaskPoolJob_t pJob,

-                                               uint32_t flags );

-

-/* @[declare_taskpool_schedulesystemjob] */

+/* @[declare_taskpool_schedule] */

 

 /**

  * @brief This function schedules a job created with @ref IotTaskPool_CreateJob against the task pool

diff --git a/FreeRTOS-Plus/Source/FreeRTOS-Plus-IoT-SDK/c_sdk/standard/common/taskpool/iot_taskpool.c b/FreeRTOS-Plus/Source/FreeRTOS-Plus-IoT-SDK/c_sdk/standard/common/taskpool/iot_taskpool.c
index fff69ca83..a01e6423c 100644
--- a/FreeRTOS-Plus/Source/FreeRTOS-Plus-IoT-SDK/c_sdk/standard/common/taskpool/iot_taskpool.c
+++ b/FreeRTOS-Plus/Source/FreeRTOS-Plus-IoT-SDK/c_sdk/standard/common/taskpool/iot_taskpool.c
@@ -32,6 +32,7 @@
 

 /* Standard includes. */

 #include <stdbool.h>

+#include <stdio.h>

 #include <stddef.h>

 #include <stdint.h>

 #include <string.h>

@@ -490,15 +491,6 @@ IotTaskPoolError_t IotTaskPool_CreateJob( IotTaskPoolRoutine_t userCallback,
 

 /*-----------------------------------------------------------*/

 

-IotTaskPoolError_t IotTaskPool_CreateRecyclableSystemJob( IotTaskPoolRoutine_t userCallback,

-                                                          void * pUserContext,

-                                                          IotTaskPoolJob_t * const pJob )

-{

-    return IotTaskPool_CreateRecyclableJob ( &_IotSystemTaskPool, userCallback, pUserContext, pJob );

-}

-

-/*-----------------------------------------------------------*/

-

 IotTaskPoolError_t IotTaskPool_CreateRecyclableJob( IotTaskPool_t taskPoolHandle,

                                                     IotTaskPoolRoutine_t userCallback,

                                                     void * pUserContext,

@@ -506,11 +498,21 @@ IotTaskPoolError_t IotTaskPool_CreateRecyclableJob( IotTaskPool_t taskPoolHandle
 {

     TASKPOOL_FUNCTION_ENTRY( IOT_TASKPOOL_SUCCESS );

 

-    _taskPool_t * pTaskPool = ( _taskPool_t * ) taskPoolHandle;

+    _taskPool_t * const pTaskPool = &_IotSystemTaskPool;

     _taskPoolJob_t * pTempJob = NULL;

 

+    /* This lean version of the task pool only supports the task pool created

+    by this library (the system task pool).  NULL means use the system task

+    pool - no other values are allowed.  Use the full implementation of this

+    library if you want multiple task pools (there is more than one task in

+    each pool. */

+    configASSERT( ( taskPoolHandle == NULL ) || ( taskPoolHandle == &_IotSystemTaskPool ) );

+

+    /* Avoid compiler warnings about unused parameters if configASSERT() is not

+    defined. */

+    ( void ) taskPoolHandle;

+

     /* Parameter checking. */

-    TASKPOOL_ON_NULL_ARG_GOTO_CLEANUP( taskPoolHandle );

     TASKPOOL_ON_NULL_ARG_GOTO_CLEANUP( userCallback );

     TASKPOOL_ON_NULL_ARG_GOTO_CLEANUP( ppJob );

 

@@ -542,12 +544,21 @@ IotTaskPoolError_t IotTaskPool_DestroyRecyclableJob( IotTaskPool_t taskPoolHandl
 {

     TASKPOOL_FUNCTION_ENTRY( IOT_TASKPOOL_SUCCESS );

 

-    ( void ) taskPoolHandle;

-

     _taskPoolJob_t * pJob = ( _taskPoolJob_t * ) pJobHandle;

 

+    /* This lean version of the task pool only supports the task pool created

+    by this library (the system task pool).  NULL means use the system task

+    pool - no other values are allowed.  Use the full implementation of this

+    library if you want multiple task pools (there is more than one task in

+    each pool. */

+#warning could use a TASKPOOL macro to check value and return error.

+    configASSERT( ( taskPoolHandle == NULL ) || ( taskPoolHandle == &_IotSystemTaskPool ) );

+

+    /* Avoid compiler warnings about unused parameters if configASSERT() is not

+    defined. */

+    ( void ) taskPoolHandle;

+

     /* Parameter checking. */

-    TASKPOOL_ON_NULL_ARG_GOTO_CLEANUP( taskPoolHandle );

     TASKPOOL_ON_NULL_ARG_GOTO_CLEANUP( pJobHandle );

 

     IotTaskPool_Assert( IotLink_IsLinked( &pJob->link ) == false );

@@ -564,10 +575,19 @@ IotTaskPoolError_t IotTaskPool_RecycleJob( IotTaskPool_t taskPoolHandle,
 {

     TASKPOOL_FUNCTION_ENTRY( IOT_TASKPOOL_SUCCESS );

 

-    _taskPool_t * pTaskPool = ( _taskPool_t * ) taskPoolHandle;

+    _taskPool_t * pTaskPool = ( _taskPool_t * ) &_IotSystemTaskPool;

+

+    /* This lean version of the task pool only supports the task pool created

+    by this library (the system task pool).  NULL means use the system task

+    pool - no other values are allowed.  Use the full implementation of this

+    library if you want multiple task pools (there is more than one task in

+    each pool. */

+    configASSERT( ( taskPoolHandle == NULL ) || ( taskPoolHandle == &_IotSystemTaskPool ) );

+

+    /* Ensure unused parameters do not cause compiler warnings in case

+    configASSERT() is not defined. */

+    ( void ) taskPoolHandle;

 

-    /* Parameter checking. */

-    TASKPOOL_ON_NULL_ARG_GOTO_CLEANUP( taskPoolHandle );

     TASKPOOL_ON_NULL_ARG_GOTO_CLEANUP( pJob );

 

     taskENTER_CRITICAL();

@@ -589,12 +609,23 @@ IotTaskPoolError_t IotTaskPool_Schedule( IotTaskPool_t taskPoolHandle,
 {

     TASKPOOL_FUNCTION_ENTRY( IOT_TASKPOOL_SUCCESS );

 

-    _taskPool_t * pTaskPool = ( _taskPool_t * ) taskPoolHandle;

+    _taskPool_t * const pTaskPool = &_IotSystemTaskPool;

 

+    /* Task pool must have been created. */

     configASSERT( pTaskPool->running != false );

 

+    /* This lean version of the task pool only supports the task pool created

+    by this library (the system task pool).  NULL means use the system task

+    pool - no other values are allowed.  Use the full implementation of this

+    library if you want multiple task pools (there is more than one task in

+    each pool. */

+    configASSERT( ( taskPoolHandle == NULL ) || ( taskPoolHandle == &_IotSystemTaskPool ) );

+

+    /* Avoid compiler warnings about unused parameters if configASSERT() is not

+    defined. */

+    ( void ) taskPoolHandle;

+

     /* Parameter checking. */

-    TASKPOOL_ON_NULL_ARG_GOTO_CLEANUP( taskPoolHandle );

     TASKPOOL_ON_NULL_ARG_GOTO_CLEANUP( pJob );

     TASKPOOL_ON_ARG_ERROR_GOTO_CLEANUP( ( flags != 0UL ) && ( flags != IOT_TASKPOOL_JOB_HIGH_PRIORITY ) );

 

@@ -609,24 +640,21 @@ IotTaskPoolError_t IotTaskPool_Schedule( IotTaskPool_t taskPoolHandle,
 

 /*-----------------------------------------------------------*/

 

-IotTaskPoolError_t IotTaskPool_ScheduleSystemJob( IotTaskPoolJob_t pJob,

-                                                  uint32_t flags )

-{

-    return IotTaskPool_Schedule( &_IotSystemTaskPool, pJob, flags );

-}

-

-/*-----------------------------------------------------------*/

-

 IotTaskPoolError_t IotTaskPool_ScheduleDeferred( IotTaskPool_t taskPoolHandle,

                                                  IotTaskPoolJob_t job,

                                                  uint32_t timeMs )

 {

     TASKPOOL_FUNCTION_ENTRY( IOT_TASKPOOL_SUCCESS );

 

-    _taskPool_t * pTaskPool = ( _taskPool_t * ) taskPoolHandle;

+    _taskPool_t * pTaskPool = &_IotSystemTaskPool;

+

+    /* This lean version of the task pool only supports the task pool created

+    by this library (the system task pool).  NULL means use the system task

+    pool - no other values are allowed.  Use the full implementation of this

+    library if you want multiple task pools (there is more than one task in

+    each pool. */

+    configASSERT( ( taskPoolHandle == NULL ) || ( taskPoolHandle == &_IotSystemTaskPool ) );

 

-    /* Parameter checking. */

-    TASKPOOL_ON_NULL_ARG_GOTO_CLEANUP( taskPoolHandle );

     TASKPOOL_ON_NULL_ARG_GOTO_CLEANUP( job );

 

     if( timeMs == 0UL )

@@ -688,7 +716,8 @@ IotTaskPoolError_t IotTaskPool_GetStatus( IotTaskPool_t taskPoolHandle,
     TASKPOOL_FUNCTION_ENTRY( IOT_TASKPOOL_SUCCESS );

 

     /* Parameter checking. */

-    TASKPOOL_ON_NULL_ARG_GOTO_CLEANUP( taskPoolHandle );

+//_RB_    TASKPOOL_ON_NULL_ARG_GOTO_CLEANUP( taskPoolHandle ); /* What is the point of this parameter? */

+    ( void ) taskPoolHandle;

     TASKPOOL_ON_NULL_ARG_GOTO_CLEANUP( job );

     TASKPOOL_ON_NULL_ARG_GOTO_CLEANUP( pStatus );

     *pStatus = IOT_TASKPOOL_STATUS_UNDEFINED;

@@ -710,10 +739,14 @@ IotTaskPoolError_t IotTaskPool_TryCancel( IotTaskPool_t taskPoolHandle,
 {

     TASKPOOL_FUNCTION_ENTRY( IOT_TASKPOOL_SUCCESS );

 

-    _taskPool_t * pTaskPool = ( _taskPool_t * ) taskPoolHandle;

+    _taskPool_t * pTaskPool = &_IotSystemTaskPool;

 

-    /* Parameter checking. */

-    TASKPOOL_ON_NULL_ARG_GOTO_CLEANUP( taskPoolHandle );

+    /* This lean version of the task pool only supports the task pool created

+    by this library (the system task pool).  NULL means use the system task

+    pool - no other values are allowed.  Use the full implementation of this

+    library if you want multiple task pools (there is more than one task in

+    each pool. */

+    configASSERT( ( taskPoolHandle == NULL ) || ( taskPoolHandle == &_IotSystemTaskPool ) );

     TASKPOOL_ON_NULL_ARG_GOTO_CLEANUP( job );

 

     if( pStatus != NULL )

@@ -859,6 +892,7 @@ static IotTaskPoolError_t _createTaskPool( const IotTaskPoolInfo_t * const pInfo
 

     uint32_t count;

     uint32_t threadsCreated;

+    char cTaskName[ 10 ];

 

     /* Check input values for consistency. */

     TASKPOOL_ON_NULL_ARG_GOTO_CLEANUP( pTaskPool );

@@ -887,10 +921,12 @@ static IotTaskPoolError_t _createTaskPool( const IotTaskPoolInfo_t * const pInfo
     /* Create the minimum number of threads specified by the user, and if one fails shutdown and return error. */

     for( threadsCreated = 0; threadsCreated < pInfo->minThreads; )

     {

-        TaskHandle_t task = NULL;

+        TaskHandle_t task = NULL; //_RB_ need to check compiles with C89

+

+        snprintf( cTaskName, sizeof( cTaskName ), "pool%d", ( int ) threadsCreated );

 

         BaseType_t res = xTaskCreate( _taskPoolWorker,

-                                      NULL,

+                                      cTaskName,

                                       pInfo->stackSize,

                                       pTaskPool,

                                       pInfo->priority,

@@ -1019,7 +1055,7 @@ static void _taskPoolWorker( void * pUserContext )
                 pJob = IotLink_Container( _taskPoolJob_t, pFirst, link );

 

                 /* Update status to 'executing'. */

-                pJob->status = IOT_TASKPOOL_STATUS_COMPLETED;

+                pJob->status = IOT_TASKPOOL_STATUS_COMPLETED; /*_RB_ Should this be 'executing'? */

                 userCallback = pJob->userCallback;

             }

         }

@@ -1156,7 +1192,7 @@ static void _recycleJob( _taskPoolCache_t * const pCache,
                          _taskPoolJob_t * const pJob )

 {

     /* We should never try and recycling a job that is linked into some queue. */

-    IotTaskPool_Assert( IotLink_IsLinked( &pJob->link ) == false );

+    IotTaskPool_Assert( IotLink_IsLinked( &pJob->link ) == false );//_RB_ Seems to be duplicate of test before this is called.

 

     /* We will recycle the job if there is space in the cache. */

     if( pCache->freeCount < IOT_TASKPOOL_JOBS_RECYCLE_LIMIT )

@@ -1232,15 +1268,11 @@ static IotTaskPoolError_t _scheduleInternal( _taskPool_t * const pTaskPool,
     /* Update the job status to 'scheduled'. */

     pJob->status = IOT_TASKPOOL_STATUS_SCHEDULED;

 

-    BaseType_t higherPriorityTaskWoken;

-

     /* Append the job to the dispatch queue. */

     IotDeQueue_EnqueueTail( &pTaskPool->dispatchQueue, &pJob->link );

 

     /* Signal a worker to pick up the job. */

-    ( void ) xSemaphoreGiveFromISR( pTaskPool->dispatchSignal, &higherPriorityTaskWoken );

-

-    portYIELD_FROM_ISR( higherPriorityTaskWoken );

+    xSemaphoreGive( pTaskPool->dispatchSignal );

 

     TASKPOOL_NO_FUNCTION_CLEANUP_NOLABEL();

 }

@@ -1333,7 +1365,7 @@ static IotTaskPoolError_t _tryCancelInternal( _taskPool_t * const pTaskPool,
             {

                 bool shouldReschedule = false;

 

-                /* If the job being cancelled was at the head of the timeouts queue, then we need to reschedule the timer

+                /* If the job being canceled was at the head of the timeouts queue, then we need to reschedule the timer

                  * with the next job timeout */

                 IotLink_t * pHeadLink = IotListDouble_PeekHead( &pTaskPool->timerEventsList );