Add xQueueReset() function.

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

diff --git a/Source/include/queue.h b/Source/include/queue.h
index 80ee4f11ffab7ca574fdea8ffcd68c1056f90a95..d129f64cd483bf21ab566147ea4e2ec2a8bfcaa1 100644 (file)
--- a/Source/include/queue.h
+++ b/Source/include/queue.h
@@ -1234,6 +1234,14 @@ xQueueHandle xQueueCreateCountingSemaphore( unsigned portBASE_TYPE uxCountValue,
 portBASE_TYPE xQueueTakeMutexRecursive( xQueueHandle pxMutex, portTickType xBlockTime );\r
 portBASE_TYPE xQueueGiveMutexRecursive( xQueueHandle pxMutex );\r
 \r
+/*\r
+ * Reset a queue back to its original empty state.  pdPASS is returned if the\r
+ * queue is successfully reset.  pdFAIL is returned if the queue could not be\r
+ * reset because there are tasks blocked on the queue waiting to either\r
+ * receive from the queue or send to the queue.\r
+ */\r
+#define xQueueReset( pxQueue ) xQueueGenericReset( pxQueue, pdFALSE )\r
+\r
 /*\r
  * The registry is provided as a means for kernel aware debuggers to\r
  * locate queues, semaphores and mutexes.  Call vQueueAddToRegistry() add\r
@@ -1264,10 +1272,9 @@ portBASE_TYPE xQueueGiveMutexRecursive( xQueueHandle pxMutex );
  */\r
 xQueueHandle xQueueGenericCreate( unsigned portBASE_TYPE uxQueueLength, unsigned portBASE_TYPE uxItemSize, unsigned char ucQueueType );\r
 \r
-/* \r
- * Not a public API function, hence the 'Restricted' in the name. \r
- */\r
+/* Not public API functions. */\r
 void vQueueWaitForMessageRestricted( xQueueHandle pxQueue, portTickType xTicksToWait );\r
+portBASE_TYPE xQueueGenericReset( xQueueHandle pxQueue, portBASE_TYPE xNewQueue );\r
 \r
 \r
 #ifdef __cplusplus\r

diff --git a/Source/queue.c b/Source/queue.c
index 9dfc6790db92034a9dbeffaec0f2e210c6e55efa..19c51d759c68901338649b096fb95a5500ea39ac 100644 (file)
--- a/Source/queue.c
+++ b/Source/queue.c
@@ -163,6 +163,7 @@ void vQueueWaitForMessageRestricted( xQueueHandle pxQueue, portTickType xTicksTo
 unsigned char ucQueueGetQueueNumber( xQueueHandle pxQueue ) PRIVILEGED_FUNCTION;\r
 void vQueueSetQueueNumber( xQueueHandle pxQueue, unsigned char ucQueueNumber ) PRIVILEGED_FUNCTION;\r
 unsigned char ucQueueGetQueueType( xQueueHandle pxQueue ) PRIVILEGED_FUNCTION;\r
+portBASE_TYPE xQueueGenericReset( xQueueHandle pxQueue, portBASE_TYPE xNewQueue ) PRIVILEGED_FUNCTION;\r
 \r
 /*\r
  * Co-routine queue functions differ from task queue functions.  Co-routines are\r
@@ -261,6 +262,45 @@ static void prvCopyDataFromQueue( xQUEUE * const pxQueue, const void *pvBuffer )
  * PUBLIC QUEUE MANAGEMENT API documented in queue.h\r
  *----------------------------------------------------------*/\r
 \r
+portBASE_TYPE xQueueGenericReset( xQueueHandle pxQueue, portBASE_TYPE xNewQueue )\r
+{\r
+portBASE_TYPE xReturn = pdPASS;\r
+\r
+       configASSERT( pxQueue );\r
+\r
+       /* If the queue being reset has already been used (has not just been\r
+       created), then only reset the queue if its event lists are empty. */\r
+       if( xNewQueue != pdTRUE )\r
+       {\r
+               if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToReceive ) ) == pdFALSE )\r
+               {\r
+                       xReturn = pdFAIL;\r
+               }\r
+\r
+               if( listLIST_IS_EMPTY( &( pxQueue->xTasksWaitingToSend ) ) == pdFALSE )\r
+               {\r
+                       xReturn = pdFAIL;\r
+               }\r
+       }\r
+\r
+       if( xReturn == pdPASS )\r
+       {\r
+               pxQueue->pcTail = pxQueue->pcHead + ( pxQueue->uxLength * pxQueue->uxItemSize );\r
+               pxQueue->uxMessagesWaiting = ( unsigned portBASE_TYPE ) 0U;\r
+               pxQueue->pcWriteTo = pxQueue->pcHead;\r
+               pxQueue->pcReadFrom = pxQueue->pcHead + ( ( pxQueue->uxLength - ( unsigned portBASE_TYPE ) 1U ) * pxQueue->uxItemSize );\r
+               pxQueue->xRxLock = queueUNLOCKED;\r
+               pxQueue->xTxLock = queueUNLOCKED;\r
+\r
+               /* Ensure the event queues start with the correct state. */\r
+               vListInitialise( &( pxQueue->xTasksWaitingToSend ) );\r
+               vListInitialise( &( pxQueue->xTasksWaitingToReceive ) );\r
+       }\r
+\r
+       return xReturn;\r
+}\r
+/*-----------------------------------------------------------*/\r
+\r
 xQueueHandle xQueueGenericCreate( unsigned portBASE_TYPE uxQueueLength, unsigned portBASE_TYPE uxItemSize, unsigned char ucQueueType )\r
 {\r
 xQUEUE *pxNewQueue;\r
@@ -286,24 +326,15 @@ xQueueHandle xReturn = NULL;
                        {\r
                                /* Initialise the queue members as described above where the\r
                                queue type is defined. */\r
-                               pxNewQueue->pcTail = pxNewQueue->pcHead + ( uxQueueLength * uxItemSize );\r
-                               pxNewQueue->uxMessagesWaiting = ( unsigned portBASE_TYPE ) 0U;\r
-                               pxNewQueue->pcWriteTo = pxNewQueue->pcHead;\r
-                               pxNewQueue->pcReadFrom = pxNewQueue->pcHead + ( ( uxQueueLength - ( unsigned portBASE_TYPE ) 1U ) * uxItemSize );\r
                                pxNewQueue->uxLength = uxQueueLength;\r
                                pxNewQueue->uxItemSize = uxItemSize;\r
-                               pxNewQueue->xRxLock = queueUNLOCKED;\r
-                               pxNewQueue->xTxLock = queueUNLOCKED;\r
+                               xQueueGenericReset( pxNewQueue, pdTRUE );\r
                                #if ( configUSE_TRACE_FACILITY == 1 )\r
                                {\r
                                        pxNewQueue->ucQueueType = ucQueueType;\r
                                }\r
                                #endif /* configUSE_TRACE_FACILITY */\r
 \r
-                               /* Likewise ensure the event queues start with the correct state. */\r
-                               vListInitialise( &( pxNewQueue->xTasksWaitingToSend ) );\r
-                               vListInitialise( &( pxNewQueue->xTasksWaitingToReceive ) );\r
-\r
                                traceQUEUE_CREATE( pxNewQueue );\r
                                xReturn = pxNewQueue;\r
                        }\r