Minor changes to new queue functions plus add comments.

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

diff --git a/Source/queue.c b/Source/queue.c
index 4f093f29e6bc1930ec146ad267109c9e5517aa88..d4e0b81967875ba694a0dd240d5129a1f586aa10 100644 (file)
--- a/Source/queue.c
+++ b/Source/queue.c
@@ -445,6 +445,10 @@ signed portBASE_TYPE xQueueGenericSend( xQueueHandle pxQueue, const void * const
 signed portBASE_TYPE xEntryTimeSet = pdFALSE;\r
 xTimeOutType xTimeOut;\r
 \r
+       /* This function relaxes the coding standard somewhat to allow return\r
+       statements within the function itself.  This is done in the interest\r
+       of execution time efficiency. */\r
+\r
        for( ;; )\r
        {\r
                taskENTER_CRITICAL();\r
@@ -463,7 +467,9 @@ xTimeOutType xTimeOut;
                                        if( xTaskRemoveFromEventList( &( pxQueue->xTasksWaitingToReceive ) ) == pdTRUE )\r
                                        {\r
                                                /* The unblocked task has a priority higher than\r
-                                               our own so yield immediately. */\r
+                                               our own so yield immediately.  Yes it is ok to do\r
+                                               this from within the critical section - the kernel\r
+                                               takes care of that. */\r
                                                taskYIELD();\r
                                        }\r
                                }\r
@@ -475,11 +481,15 @@ xTimeOutType xTimeOut;
                        {\r
                                if( xTicksToWait == ( portTickType ) 0 )\r
                                {\r
+                                       /* The queue was full and no block time is specified (or \r
+                                       the block time has expired) so leave now. */\r
                                        taskEXIT_CRITICAL();\r
                                        return errQUEUE_FULL;\r
                                }\r
                                else if( xEntryTimeSet == pdFALSE )\r
                                {\r
+                                       /* The queue was full and a block time was specified so\r
+                                       configure the timeout structure. */\r
                                        vTaskSetTimeOutState( &xTimeOut );\r
                                        xEntryTimeSet = pdTRUE;\r
                                }\r
@@ -487,16 +497,17 @@ xTimeOutType xTimeOut;
                }\r
                taskEXIT_CRITICAL();    \r
 \r
+               /* Interrupts and other tasks can send to and receive from the queue\r
+               now the critical section has been exited. */\r
+\r
                vTaskSuspendAll();\r
                prvLockQueue( pxQueue );\r
 \r
-               if( prvIsQueueFull( pxQueue ) )\r
+               /* Update the timeout state to see if it has expired yet. */\r
+               if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) == pdFALSE )\r
                {\r
-               /* Need to call xTaskCheckForTimeout again as time could\r
-               have passed since it was last called if this is not the\r
-               first time around this loop.  */\r
-                       if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) == pdFALSE )\r
-                       {\r
+                       if( prvIsQueueFull( pxQueue ) )\r
+                       {               \r
                                traceBLOCKING_ON_QUEUE_SEND( pxQueue );\r
                                vTaskPlaceOnEventList( &( pxQueue->xTasksWaitingToSend ), xTicksToWait );\r
 \r
@@ -519,15 +530,17 @@ xTimeOutType xTimeOut;
                        }\r
                        else\r
                        {\r
+                               /* Try again. */\r
                                prvUnlockQueue( pxQueue );\r
-                               ( void ) xTaskResumeAll();\r
-                               return errQUEUE_FULL;\r
+                               ( void ) xTaskResumeAll();                      \r
                        }\r
                }\r
                else\r
                {\r
+                       /* The timeout has expired. */\r
                        prvUnlockQueue( pxQueue );\r
                        ( void ) xTaskResumeAll();\r
+                       return errQUEUE_FULL;\r
                }\r
        }\r
 }\r
@@ -584,22 +597,19 @@ xTimeOutType xTimeOut;
 \r
                        taskENTER_CRITICAL();\r
                        {\r
-                               if( prvIsQueueFull( pxQueue ) )\r
+                               if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) == pdFALSE )\r
                                {\r
-                               /* Need to call xTaskCheckForTimeout again as time could\r
-                               have passed since it was last called if this is not the\r
-                               first time around this loop.  */\r
-                                       if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) == pdFALSE )\r
-                                       {\r
+                                       if( prvIsQueueFull( pxQueue ) )\r
+                                       {                               \r
                                                traceBLOCKING_ON_QUEUE_SEND( pxQueue );\r
                                                vTaskPlaceOnEventList( &( pxQueue->xTasksWaitingToSend ), xTicksToWait );\r
                                                taskYIELD();\r
                                        }\r
-                                       else\r
-                                       {\r
-                                               taskEXIT_CRITICAL();\r
-                                               return errQUEUE_FULL;\r
-                                       }\r
+                               }\r
+                               else\r
+                               {\r
+                                       taskEXIT_CRITICAL();\r
+                                       return errQUEUE_FULL;\r
                                }\r
                        }\r
                        taskEXIT_CRITICAL();\r
@@ -698,13 +708,10 @@ xTimeOutType xTimeOut;
 \r
                        taskENTER_CRITICAL();\r
                        {\r
-                               if( prvIsQueueEmpty( pxQueue ) )\r
+                               if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) == pdFALSE )\r
                                {\r
-                               /* Need to call xTaskCheckForTimeout again as time could\r
-                               have passed since it was last called if this is not the\r
-                               first time around this loop. */\r
-                                       if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) == pdFALSE )\r
-                                       {\r
+                                       if( prvIsQueueEmpty( pxQueue ) )\r
+                                       {                               \r
                                                traceBLOCKING_ON_QUEUE_RECEIVE( pxQueue );\r
 \r
                                                #if ( configUSE_MUTEXES == 1 )\r
@@ -721,11 +728,11 @@ xTimeOutType xTimeOut;
                                                vTaskPlaceOnEventList( &( pxQueue->xTasksWaitingToReceive ), xTicksToWait );\r
                                                taskYIELD();\r
                                        }\r
-                                       else\r
-                                       {\r
-                                               taskEXIT_CRITICAL();\r
-                                               return errQUEUE_EMPTY;\r
-                                       }\r
+                               }\r
+                               else\r
+                               {\r
+                                       taskEXIT_CRITICAL();\r
+                                       return errQUEUE_EMPTY;\r
                                }\r
                        }\r
                        taskEXIT_CRITICAL();\r
@@ -795,10 +802,16 @@ signed portBASE_TYPE xEntryTimeSet = pdFALSE;
 xTimeOutType xTimeOut;\r
 signed portCHAR *pcOriginalReadPosition;\r
 \r
+       /* This function relaxes the coding standard somewhat to allow return\r
+       statements within the function itself.  This is done in the interest\r
+       of execution time efficiency. */\r
+\r
        for( ;; )\r
        {\r
                taskENTER_CRITICAL();\r
                {\r
+                       /* Is there space on the queue now?  To be running we must be\r
+                       the highest priority task wanting to access the queue. */               \r
                        if( pxQueue->uxMessagesWaiting > ( unsigned portBASE_TYPE ) 0 )\r
                        {\r
                                /* Remember our read position in case we are just peeking. */\r
@@ -862,11 +875,15 @@ signed portCHAR *pcOriginalReadPosition;
                        {\r
                                if( xTicksToWait == ( portTickType ) 0 )\r
                                {\r
+                                       /* The queue was empty and no block time is specified (or \r
+                                       the block time has expired) so leave now. */                            \r
                                        taskEXIT_CRITICAL();\r
                                        return errQUEUE_EMPTY;\r
                                }\r
                                else if( xEntryTimeSet == pdFALSE )\r
                                {\r
+                                       /* The queue was empty and a block time was specified so\r
+                                       configure the timeout structure. */                             \r
                                        vTaskSetTimeOutState( &xTimeOut );\r
                                        xEntryTimeSet = pdTRUE;\r
                                }\r
@@ -874,15 +891,16 @@ signed portCHAR *pcOriginalReadPosition;
                }\r
                taskEXIT_CRITICAL();\r
 \r
+               /* Interrupts and other tasks can send to and receive from the queue\r
+               now the critical section has been exited. */\r
+\r
                vTaskSuspendAll();\r
                prvLockQueue( pxQueue );\r
 \r
-               if( prvIsQueueEmpty( pxQueue ) )\r
+               /* Update the timeout state to see if it has expired yet. */\r
+               if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) == pdFALSE )\r
                {\r
-               /* Need to call xTaskCheckForTimeout again as time could\r
-               have passed since it was last called if this is not the\r
-               first time around this loop. */\r
-                       if( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait ) == pdFALSE )\r
+                       if( prvIsQueueEmpty( pxQueue ) )\r
                        {\r
                                traceBLOCKING_ON_QUEUE_RECEIVE( pxQueue );\r
 \r
@@ -891,7 +909,9 @@ signed portCHAR *pcOriginalReadPosition;
                                        if( pxQueue->uxQueueType == queueQUEUE_IS_MUTEX )\r
                                        {\r
                                                portENTER_CRITICAL();\r
+                                               {\r
                                                        vTaskPriorityInherit( ( void * ) pxQueue->pxMutexHolder );\r
+                                               }\r
                                                portEXIT_CRITICAL();\r
                                        }\r
                                }\r
@@ -906,15 +926,16 @@ signed portCHAR *pcOriginalReadPosition;
                        }\r
                        else\r
                        {\r
+                               /* Try again. */\r
                                prvUnlockQueue( pxQueue );\r
                                ( void ) xTaskResumeAll();\r
-                               return errQUEUE_EMPTY;\r
                        }\r
                }\r
                else\r
                {\r
                        prvUnlockQueue( pxQueue );\r
                        ( void ) xTaskResumeAll();\r
+                       return errQUEUE_EMPTY;\r
                }\r
        }\r
 }\r