git.sur5r.net Git - freertos/blob - Source/include/queue.h

   1 /*\r
   2         FreeRTOS.org V5.2.0 - Copyright (C) 2003-2009 Richard Barry.\r
   3 \r
   4         This file is part of the FreeRTOS.org distribution.\r
   5 \r
   6         FreeRTOS.org is free software; you can redistribute it and/or modify it \r
   7         under the terms of the GNU General Public License (version 2) as published\r
   8         by the Free Software Foundation and modified by the FreeRTOS exception.\r
   9 \r
  10         FreeRTOS.org is distributed in the hope that it will be useful, but WITHOUT\r
  11         ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or \r
  12         FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for \r
  13         more details.\r
  14 \r
  15         You should have received a copy of the GNU General Public License along \r
  16         with FreeRTOS.org; if not, write to the Free Software Foundation, Inc., 59 \r
  17         Temple Place, Suite 330, Boston, MA  02111-1307  USA.\r
  18 \r
  19         A special exception to the GPL is included to allow you to distribute a \r
  20         combined work that includes FreeRTOS.org without being obliged to provide\r
  21         the source code for any proprietary components.  See the licensing section\r
  22         of http://www.FreeRTOS.org for full details.\r
  23 \r
  24 \r
  25         ***************************************************************************\r
  26         *                                                                         *\r
  27         * Get the FreeRTOS eBook!  See http://www.FreeRTOS.org/Documentation      *\r
  28         *                                                                         *\r
  29         * This is a concise, step by step, 'hands on' guide that describes both   *\r
  30         * general multitasking concepts and FreeRTOS specifics. It presents and   *\r
  31         * explains numerous examples that are written using the FreeRTOS API.     *\r
  32         * Full source code for all the examples is provided in an accompanying    *\r
  33         * .zip file.                                                              *\r
  34         *                                                                         *\r
  35         ***************************************************************************\r
  36 \r
  37         1 tab == 4 spaces!\r
  38 \r
  39         Please ensure to read the configuration and relevant port sections of the\r
  40         online documentation.\r
  41 \r
  42         http://www.FreeRTOS.org - Documentation, latest information, license and\r
  43         contact details.\r
  44 \r
  45         http://www.SafeRTOS.com - A version that is certified for use in safety\r
  46         critical systems.\r
  47 \r
  48         http://www.OpenRTOS.com - Commercial support, development, porting,\r
  49         licensing and training services.\r
  50 */\r
  51 \r
  52 #ifndef INC_FREERTOS_H\r
  53         #error "#include FreeRTOS.h" must appear in source files before "#include queue.h"\r
  54 #endif\r
  55 \r
  56 \r
  57 \r
  58 \r
  59 #ifndef QUEUE_H\r
  60 #define QUEUE_H\r
  61 \r
  62 #ifdef __cplusplus\r
  63 extern "C" {\r
  64 #endif\r
  65 typedef void * xQueueHandle;\r
  66 \r
  67 /* For internal use only. */\r
  68 #define queueSEND_TO_BACK       ( 0 )\r
  69 #define queueSEND_TO_FRONT      ( 1 )\r
  70 \r
  71 \r
  72 /**\r
  73  * queue. h\r
  74  * <pre>\r
  75  xQueueHandle xQueueCreate(\r
  76                               unsigned portBASE_TYPE uxQueueLength,\r
  77                               unsigned portBASE_TYPE uxItemSize\r
  78                           );\r
  79  * </pre>\r
  80  *\r
  81  * Creates a new queue instance.  This allocates the storage required by the\r
  82  * new queue and returns a handle for the queue.\r
  83  *\r
  84  * @param uxQueueLength The maximum number of items that the queue can contain.\r
  85  *\r
  86  * @param uxItemSize The number of bytes each item in the queue will require.\r
  87  * Items are queued by copy, not by reference, so this is the number of bytes\r
  88  * that will be copied for each posted item.  Each item on the queue must be\r
  89  * the same size.\r
  90  *\r
  91  * @return If the queue is successfully create then a handle to the newly\r
  92  * created queue is returned.  If the queue cannot be created then 0 is\r
  93  * returned.\r
  94  *\r
  95  * Example usage:\r
  96    <pre>\r
  97  struct AMessage\r
  98  {\r
  99     portCHAR ucMessageID;\r
 100     portCHAR ucData[ 20 ];\r
 101  };\r
 102 \r
 103  void vATask( void *pvParameters )\r
 104  {\r
 105  xQueueHandle xQueue1, xQueue2;\r
 106 \r
 107     // Create a queue capable of containing 10 unsigned long values.\r
 108     xQueue1 = xQueueCreate( 10, sizeof( unsigned portLONG ) );\r
 109     if( xQueue1 == 0 )\r
 110     {\r
 111         // Queue was not created and must not be used.\r
 112     }\r
 113 \r
 114     // Create a queue capable of containing 10 pointers to AMessage structures.\r
 115     // These should be passed by pointer as they contain a lot of data.\r
 116     xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );\r
 117     if( xQueue2 == 0 )\r
 118     {\r
 119         // Queue was not created and must not be used.\r
 120     }\r
 121 \r
 122     // ... Rest of task code.\r
 123  }\r
 124  </pre>\r
 125  * \defgroup xQueueCreate xQueueCreate\r
 126  * \ingroup QueueManagement\r
 127  */\r
 128 xQueueHandle xQueueCreate( unsigned portBASE_TYPE uxQueueLength, unsigned portBASE_TYPE uxItemSize );\r
 129 \r
 130 /**\r
 131  * queue. h\r
 132  * <pre>\r
 133  portBASE_TYPE xQueueSendToToFront(\r
 134                                    xQueueHandle xQueue,\r
 135                                    const void * pvItemToQueue,\r
 136                                    portTickType xTicksToWait\r
 137                                );\r
 138  * </pre>\r
 139  *\r
 140  * This is a macro that calls xQueueGenericSend().\r
 141  *\r
 142  * Post an item to the front of a queue.  The item is queued by copy, not by\r
 143  * reference.  This function must not be called from an interrupt service\r
 144  * routine.  See xQueueSendFromISR () for an alternative which may be used\r
 145  * in an ISR.\r
 146  *\r
 147  * @param xQueue The handle to the queue on which the item is to be posted.\r
 148  *\r
 149  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
 150  * queue.  The size of the items the queue will hold was defined when the\r
 151  * queue was created, so this many bytes will be copied from pvItemToQueue\r
 152  * into the queue storage area.\r
 153  *\r
 154  * @param xTicksToWait The maximum amount of time the task should block\r
 155  * waiting for space to become available on the queue, should it already\r
 156  * be full.  The call will return immediately if this is set to 0 and the\r
 157  * queue is full.  The time is defined in tick periods so the constant \r
 158  * portTICK_RATE_MS should be used to convert to real time if this is required.\r
 159  *\r
 160  * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.\r
 161  *\r
 162  * Example usage:\r
 163    <pre>\r
 164  struct AMessage\r
 165  {\r
 166     portCHAR ucMessageID;\r
 167     portCHAR ucData[ 20 ];\r
 168  } xMessage;\r
 169 \r
 170  unsigned portLONG ulVar = 10UL;\r
 171 \r
 172  void vATask( void *pvParameters )\r
 173  {\r
 174  xQueueHandle xQueue1, xQueue2;\r
 175  struct AMessage *pxMessage;\r
 176 \r
 177     // Create a queue capable of containing 10 unsigned long values.\r
 178     xQueue1 = xQueueCreate( 10, sizeof( unsigned portLONG ) );\r
 179 \r
 180     // Create a queue capable of containing 10 pointers to AMessage structures.\r
 181     // These should be passed by pointer as they contain a lot of data.\r
 182     xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );\r
 183 \r
 184     // ...\r
 185 \r
 186     if( xQueue1 != 0 )\r
 187     {\r
 188         // Send an unsigned long.  Wait for 10 ticks for space to become\r
 189         // available if necessary.\r
 190         if( xQueueSendToFront( xQueue1, ( void * ) &ulVar, ( portTickType ) 10 ) != pdPASS )\r
 191         {\r
 192             // Failed to post the message, even after 10 ticks.\r
 193         }\r
 194     }\r
 195 \r
 196     if( xQueue2 != 0 )\r
 197     {\r
 198         // Send a pointer to a struct AMessage object.  Don't block if the\r
 199         // queue is already full.\r
 200         pxMessage = & xMessage;\r
 201         xQueueSendToFront( xQueue2, ( void * ) &pxMessage, ( portTickType ) 0 );\r
 202     }\r
 203 \r
 204         // ... Rest of task code.\r
 205  }\r
 206  </pre>\r
 207  * \defgroup xQueueSend xQueueSend\r
 208  * \ingroup QueueManagement\r
 209  */\r
 210 #define xQueueSendToFront( xQueue, pvItemToQueue, xTicksToWait ) xQueueGenericSend( xQueue, pvItemToQueue, xTicksToWait, queueSEND_TO_FRONT )\r
 211 \r
 212 /**\r
 213  * queue. h\r
 214  * <pre>\r
 215  portBASE_TYPE xQueueSendToBack(\r
 216                                    xQueueHandle xQueue,\r
 217                                    const void * pvItemToQueue,\r
 218                                    portTickType xTicksToWait\r
 219                                );\r
 220  * </pre>\r
 221  *\r
 222  * This is a macro that calls xQueueGenericSend().\r
 223  *\r
 224  * Post an item to the back of a queue.  The item is queued by copy, not by\r
 225  * reference.  This function must not be called from an interrupt service\r
 226  * routine.  See xQueueSendFromISR () for an alternative which may be used\r
 227  * in an ISR.\r
 228  *\r
 229  * @param xQueue The handle to the queue on which the item is to be posted.\r
 230  *\r
 231  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
 232  * queue.  The size of the items the queue will hold was defined when the\r
 233  * queue was created, so this many bytes will be copied from pvItemToQueue\r
 234  * into the queue storage area.\r
 235  *\r
 236  * @param xTicksToWait The maximum amount of time the task should block\r
 237  * waiting for space to become available on the queue, should it already\r
 238  * be full.  The call will return immediately if this is set to 0 and the queue\r
 239  * is full.  The  time is defined in tick periods so the constant \r
 240  * portTICK_RATE_MS should be used to convert to real time if this is required.\r
 241  *\r
 242  * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.\r
 243  *\r
 244  * Example usage:\r
 245    <pre>\r
 246  struct AMessage\r
 247  {\r
 248     portCHAR ucMessageID;\r
 249     portCHAR ucData[ 20 ];\r
 250  } xMessage;\r
 251 \r
 252  unsigned portLONG ulVar = 10UL;\r
 253 \r
 254  void vATask( void *pvParameters )\r
 255  {\r
 256  xQueueHandle xQueue1, xQueue2;\r
 257  struct AMessage *pxMessage;\r
 258 \r
 259     // Create a queue capable of containing 10 unsigned long values.\r
 260     xQueue1 = xQueueCreate( 10, sizeof( unsigned portLONG ) );\r
 261 \r
 262     // Create a queue capable of containing 10 pointers to AMessage structures.\r
 263     // These should be passed by pointer as they contain a lot of data.\r
 264     xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );\r
 265 \r
 266     // ...\r
 267 \r
 268     if( xQueue1 != 0 )\r
 269     {\r
 270         // Send an unsigned long.  Wait for 10 ticks for space to become\r
 271         // available if necessary.\r
 272         if( xQueueSendToBack( xQueue1, ( void * ) &ulVar, ( portTickType ) 10 ) != pdPASS )\r
 273         {\r
 274             // Failed to post the message, even after 10 ticks.\r
 275         }\r
 276     }\r
 277 \r
 278     if( xQueue2 != 0 )\r
 279     {\r
 280         // Send a pointer to a struct AMessage object.  Don't block if the\r
 281         // queue is already full.\r
 282         pxMessage = & xMessage;\r
 283         xQueueSendToBack( xQueue2, ( void * ) &pxMessage, ( portTickType ) 0 );\r
 284     }\r
 285 \r
 286         // ... Rest of task code.\r
 287  }\r
 288  </pre>\r
 289  * \defgroup xQueueSend xQueueSend\r
 290  * \ingroup QueueManagement\r
 291  */\r
 292 #define xQueueSendToBack( xQueue, pvItemToQueue, xTicksToWait ) xQueueGenericSend( xQueue, pvItemToQueue, xTicksToWait, queueSEND_TO_BACK )\r
 293 \r
 294 /**\r
 295  * queue. h\r
 296  * <pre>\r
 297  portBASE_TYPE xQueueSend(\r
 298                               xQueueHandle xQueue,\r
 299                               const void * pvItemToQueue,\r
 300                               portTickType xTicksToWait\r
 301                          );\r
 302  * </pre>\r
 303  *\r
 304  * This is a macro that calls xQueueGenericSend().  It is included for\r
 305  * backward compatibility with versions of FreeRTOS.org that did not\r
 306  * include the xQueueSendToFront() and xQueueSendToBack() macros.  It is\r
 307  * equivalent to xQueueSendToBack().\r
 308  *\r
 309  * Post an item on a queue.  The item is queued by copy, not by reference.\r
 310  * This function must not be called from an interrupt service routine.\r
 311  * See xQueueSendFromISR () for an alternative which may be used in an ISR.\r
 312  *\r
 313  * @param xQueue The handle to the queue on which the item is to be posted.\r
 314  *\r
 315  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
 316  * queue.  The size of the items the queue will hold was defined when the\r
 317  * queue was created, so this many bytes will be copied from pvItemToQueue\r
 318  * into the queue storage area.\r
 319  *\r
 320  * @param xTicksToWait The maximum amount of time the task should block\r
 321  * waiting for space to become available on the queue, should it already\r
 322  * be full.  The call will return immediately if this is set to 0 and the\r
 323  * queue is full.  The time is defined in tick periods so the constant \r
 324  * portTICK_RATE_MS should be used to convert to real time if this is required.\r
 325  *\r
 326  * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.\r
 327  *\r
 328  * Example usage:\r
 329    <pre>\r
 330  struct AMessage\r
 331  {\r
 332     portCHAR ucMessageID;\r
 333     portCHAR ucData[ 20 ];\r
 334  } xMessage;\r
 335 \r
 336  unsigned portLONG ulVar = 10UL;\r
 337 \r
 338  void vATask( void *pvParameters )\r
 339  {\r
 340  xQueueHandle xQueue1, xQueue2;\r
 341  struct AMessage *pxMessage;\r
 342 \r
 343     // Create a queue capable of containing 10 unsigned long values.\r
 344     xQueue1 = xQueueCreate( 10, sizeof( unsigned portLONG ) );\r
 345 \r
 346     // Create a queue capable of containing 10 pointers to AMessage structures.\r
 347     // These should be passed by pointer as they contain a lot of data.\r
 348     xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );\r
 349 \r
 350     // ...\r
 351 \r
 352     if( xQueue1 != 0 )\r
 353     {\r
 354         // Send an unsigned long.  Wait for 10 ticks for space to become\r
 355         // available if necessary.\r
 356         if( xQueueSend( xQueue1, ( void * ) &ulVar, ( portTickType ) 10 ) != pdPASS )\r
 357         {\r
 358             // Failed to post the message, even after 10 ticks.\r
 359         }\r
 360     }\r
 361 \r
 362     if( xQueue2 != 0 )\r
 363     {\r
 364         // Send a pointer to a struct AMessage object.  Don't block if the\r
 365         // queue is already full.\r
 366         pxMessage = & xMessage;\r
 367         xQueueSend( xQueue2, ( void * ) &pxMessage, ( portTickType ) 0 );\r
 368     }\r
 369 \r
 370         // ... Rest of task code.\r
 371  }\r
 372  </pre>\r
 373  * \defgroup xQueueSend xQueueSend\r
 374  * \ingroup QueueManagement\r
 375  */\r
 376 #define xQueueSend( xQueue, pvItemToQueue, xTicksToWait ) xQueueGenericSend( xQueue, pvItemToQueue, xTicksToWait, queueSEND_TO_BACK )\r
 377 \r
 378 \r
 379 /**\r
 380  * queue. h\r
 381  * <pre>\r
 382  portBASE_TYPE xQueueGenericSend(\r
 383                                                                         xQueueHandle xQueue,\r
 384                                                                         const void * pvItemToQueue,\r
 385                                                                         portTickType xTicksToWait\r
 386                                                                         portBASE_TYPE xCopyPosition\r
 387                                                                 );\r
 388  * </pre>\r
 389  *\r
 390  * It is preferred that the macros xQueueSend(), xQueueSendToFront() and\r
 391  * xQueueSendToBack() are used in place of calling this function directly.\r
 392  *\r
 393  * Post an item on a queue.  The item is queued by copy, not by reference.\r
 394  * This function must not be called from an interrupt service routine.\r
 395  * See xQueueSendFromISR () for an alternative which may be used in an ISR.\r
 396  *\r
 397  * @param xQueue The handle to the queue on which the item is to be posted.\r
 398  *\r
 399  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
 400  * queue.  The size of the items the queue will hold was defined when the\r
 401  * queue was created, so this many bytes will be copied from pvItemToQueue\r
 402  * into the queue storage area.\r
 403  *\r
 404  * @param xTicksToWait The maximum amount of time the task should block\r
 405  * waiting for space to become available on the queue, should it already\r
 406  * be full.  The call will return immediately if this is set to 0 and the\r
 407  * queue is full.  The time is defined in tick periods so the constant \r
 408  * portTICK_RATE_MS should be used to convert to real time if this is required.\r
 409  *\r
 410  * @param xCopyPosition Can take the value queueSEND_TO_BACK to place the\r
 411  * item at the back of the queue, or queueSEND_TO_FRONT to place the item\r
 412  * at the front of the queue (for high priority messages).\r
 413  *\r
 414  * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.\r
 415  *\r
 416  * Example usage:\r
 417    <pre>\r
 418  struct AMessage\r
 419  {\r
 420     portCHAR ucMessageID;\r
 421     portCHAR ucData[ 20 ];\r
 422  } xMessage;\r
 423 \r
 424  unsigned portLONG ulVar = 10UL;\r
 425 \r
 426  void vATask( void *pvParameters )\r
 427  {\r
 428  xQueueHandle xQueue1, xQueue2;\r
 429  struct AMessage *pxMessage;\r
 430 \r
 431     // Create a queue capable of containing 10 unsigned long values.\r
 432     xQueue1 = xQueueCreate( 10, sizeof( unsigned portLONG ) );\r
 433 \r
 434     // Create a queue capable of containing 10 pointers to AMessage structures.\r
 435     // These should be passed by pointer as they contain a lot of data.\r
 436     xQueue2 = xQueueCreate( 10, sizeof( struct AMessage * ) );\r
 437 \r
 438     // ...\r
 439 \r
 440     if( xQueue1 != 0 )\r
 441     {\r
 442         // Send an unsigned long.  Wait for 10 ticks for space to become\r
 443         // available if necessary.\r
 444         if( xQueueGenericSend( xQueue1, ( void * ) &ulVar, ( portTickType ) 10, queueSEND_TO_BACK ) != pdPASS )\r
 445         {\r
 446             // Failed to post the message, even after 10 ticks.\r
 447         }\r
 448     }\r
 449 \r
 450     if( xQueue2 != 0 )\r
 451     {\r
 452         // Send a pointer to a struct AMessage object.  Don't block if the\r
 453         // queue is already full.\r
 454         pxMessage = & xMessage;\r
 455         xQueueGenericSend( xQueue2, ( void * ) &pxMessage, ( portTickType ) 0, queueSEND_TO_BACK );\r
 456     }\r
 457 \r
 458         // ... Rest of task code.\r
 459  }\r
 460  </pre>\r
 461  * \defgroup xQueueSend xQueueSend\r
 462  * \ingroup QueueManagement\r
 463  */\r
 464 signed portBASE_TYPE xQueueGenericSend( xQueueHandle xQueue, const void * const pvItemToQueue, portTickType xTicksToWait, portBASE_TYPE xCopyPosition );\r
 465 \r
 466 /**\r
 467  * queue. h\r
 468  * <pre>\r
 469  portBASE_TYPE xQueuePeek(\r
 470                              xQueueHandle xQueue,\r
 471                              void *pvBuffer,\r
 472                              portTickType xTicksToWait\r
 473                          );</pre>\r
 474  *\r
 475  * This is a macro that calls the xQueueGenericReceive() function.\r
 476  *\r
 477  * Receive an item from a queue without removing the item from the queue.\r
 478  * The item is received by copy so a buffer of adequate size must be\r
 479  * provided.  The number of bytes copied into the buffer was defined when\r
 480  * the queue was created.\r
 481  *\r
 482  * Successfully received items remain on the queue so will be returned again\r
 483  * by the next call, or a call to xQueueReceive().\r
 484  *\r
 485  * This macro must not be used in an interrupt service routine.\r
 486  *\r
 487  * @param pxQueue The handle to the queue from which the item is to be\r
 488  * received.\r
 489  *\r
 490  * @param pvBuffer Pointer to the buffer into which the received item will\r
 491  * be copied.\r
 492  *\r
 493  * @param xTicksToWait The maximum amount of time the task should block\r
 494  * waiting for an item to receive should the queue be empty at the time\r
 495  * of the call.    The time is defined in tick periods so the constant\r
 496  * portTICK_RATE_MS should be used to convert to real time if this is required.\r
 497  * xQueuePeek() will return immediately if xTicksToWait is 0 and the queue\r
 498  * is empty.\r
 499  *\r
 500  * @return pdTRUE if an item was successfully received from the queue,\r
 501  * otherwise pdFALSE.\r
 502  *\r
 503  * Example usage:\r
 504    <pre>\r
 505  struct AMessage\r
 506  {\r
 507     portCHAR ucMessageID;\r
 508     portCHAR ucData[ 20 ];\r
 509  } xMessage;\r
 510 \r
 511  xQueueHandle xQueue;\r
 512 \r
 513  // Task to create a queue and post a value.\r
 514  void vATask( void *pvParameters )\r
 515  {\r
 516  struct AMessage *pxMessage;\r
 517 \r
 518     // Create a queue capable of containing 10 pointers to AMessage structures.\r
 519     // These should be passed by pointer as they contain a lot of data.\r
 520     xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) );\r
 521     if( xQueue == 0 )\r
 522     {\r
 523         // Failed to create the queue.\r
 524     }\r
 525 \r
 526     // ...\r
 527 \r
 528     // Send a pointer to a struct AMessage object.  Don't block if the\r
 529     // queue is already full.\r
 530     pxMessage = & xMessage;\r
 531     xQueueSend( xQueue, ( void * ) &pxMessage, ( portTickType ) 0 );\r
 532 \r
 533         // ... Rest of task code.\r
 534  }\r
 535 \r
 536  // Task to peek the data from the queue.\r
 537  void vADifferentTask( void *pvParameters )\r
 538  {\r
 539  struct AMessage *pxRxedMessage;\r
 540 \r
 541     if( xQueue != 0 )\r
 542     {\r
 543         // Peek a message on the created queue.  Block for 10 ticks if a\r
 544         // message is not immediately available.\r
 545         if( xQueuePeek( xQueue, &( pxRxedMessage ), ( portTickType ) 10 ) )\r
 546         {\r
 547             // pcRxedMessage now points to the struct AMessage variable posted\r
 548             // by vATask, but the item still remains on the queue.\r
 549         }\r
 550     }\r
 551 \r
 552         // ... Rest of task code.\r
 553  }\r
 554  </pre>\r
 555  * \defgroup xQueueReceive xQueueReceive\r
 556  * \ingroup QueueManagement\r
 557  */\r
 558 #define xQueuePeek( xQueue, pvBuffer, xTicksToWait ) xQueueGenericReceive( xQueue, pvBuffer, xTicksToWait, pdTRUE )\r
 559 \r
 560 /**\r
 561  * queue. h\r
 562  * <pre>\r
 563  portBASE_TYPE xQueueReceive(\r
 564                                  xQueueHandle xQueue,\r
 565                                  void *pvBuffer,\r
 566                                  portTickType xTicksToWait\r
 567                             );</pre>\r
 568  *\r
 569  * This is a macro that calls the xQueueGenericReceive() function.\r
 570  *\r
 571  * Receive an item from a queue.  The item is received by copy so a buffer of\r
 572  * adequate size must be provided.  The number of bytes copied into the buffer\r
 573  * was defined when the queue was created.\r
 574  *\r
 575  * Successfully received items are removed from the queue.\r
 576  *\r
 577  * This function must not be used in an interrupt service routine.  See\r
 578  * xQueueReceiveFromISR for an alternative that can.\r
 579  *\r
 580  * @param pxQueue The handle to the queue from which the item is to be\r
 581  * received.\r
 582  *\r
 583  * @param pvBuffer Pointer to the buffer into which the received item will\r
 584  * be copied.\r
 585  *\r
 586  * @param xTicksToWait The maximum amount of time the task should block\r
 587  * waiting for an item to receive should the queue be empty at the time\r
 588  * of the call.    xQueueReceive() will return immediately if xTicksToWait\r
 589  * is zero and the queue is empty.  The time is defined in tick periods so the \r
 590  * constant portTICK_RATE_MS should be used to convert to real time if this is \r
 591  * required.\r
 592  *\r
 593  * @return pdTRUE if an item was successfully received from the queue,\r
 594  * otherwise pdFALSE.\r
 595  *\r
 596  * Example usage:\r
 597    <pre>\r
 598  struct AMessage\r
 599  {\r
 600     portCHAR ucMessageID;\r
 601     portCHAR ucData[ 20 ];\r
 602  } xMessage;\r
 603 \r
 604  xQueueHandle xQueue;\r
 605 \r
 606  // Task to create a queue and post a value.\r
 607  void vATask( void *pvParameters )\r
 608  {\r
 609  struct AMessage *pxMessage;\r
 610 \r
 611     // Create a queue capable of containing 10 pointers to AMessage structures.\r
 612     // These should be passed by pointer as they contain a lot of data.\r
 613     xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) );\r
 614     if( xQueue == 0 )\r
 615     {\r
 616         // Failed to create the queue.\r
 617     }\r
 618 \r
 619     // ...\r
 620 \r
 621     // Send a pointer to a struct AMessage object.  Don't block if the\r
 622     // queue is already full.\r
 623     pxMessage = & xMessage;\r
 624     xQueueSend( xQueue, ( void * ) &pxMessage, ( portTickType ) 0 );\r
 625 \r
 626         // ... Rest of task code.\r
 627  }\r
 628 \r
 629  // Task to receive from the queue.\r
 630  void vADifferentTask( void *pvParameters )\r
 631  {\r
 632  struct AMessage *pxRxedMessage;\r
 633 \r
 634     if( xQueue != 0 )\r
 635     {\r
 636         // Receive a message on the created queue.  Block for 10 ticks if a\r
 637         // message is not immediately available.\r
 638         if( xQueueReceive( xQueue, &( pxRxedMessage ), ( portTickType ) 10 ) )\r
 639         {\r
 640             // pcRxedMessage now points to the struct AMessage variable posted\r
 641             // by vATask.\r
 642         }\r
 643     }\r
 644 \r
 645         // ... Rest of task code.\r
 646  }\r
 647  </pre>\r
 648  * \defgroup xQueueReceive xQueueReceive\r
 649  * \ingroup QueueManagement\r
 650  */\r
 651 #define xQueueReceive( xQueue, pvBuffer, xTicksToWait ) xQueueGenericReceive( xQueue, pvBuffer, xTicksToWait, pdFALSE )\r
 652 \r
 653 \r
 654 /**\r
 655  * queue. h\r
 656  * <pre>\r
 657  portBASE_TYPE xQueueGenericReceive(\r
 658                                        xQueueHandle xQueue,\r
 659                                        void *pvBuffer,\r
 660                                        portTickType xTicksToWait\r
 661                                        portBASE_TYPE xJustPeek\r
 662                                     );</pre>\r
 663  *\r
 664  * It is preferred that the macro xQueueReceive() be used rather than calling\r
 665  * this function directly.\r
 666  *\r
 667  * Receive an item from a queue.  The item is received by copy so a buffer of\r
 668  * adequate size must be provided.  The number of bytes copied into the buffer\r
 669  * was defined when the queue was created.\r
 670  *\r
 671  * This function must not be used in an interrupt service routine.  See\r
 672  * xQueueReceiveFromISR for an alternative that can.\r
 673  *\r
 674  * @param pxQueue The handle to the queue from which the item is to be\r
 675  * received.\r
 676  *\r
 677  * @param pvBuffer Pointer to the buffer into which the received item will\r
 678  * be copied.\r
 679  *\r
 680  * @param xTicksToWait The maximum amount of time the task should block\r
 681  * waiting for an item to receive should the queue be empty at the time\r
 682  * of the call.    The time is defined in tick periods so the constant\r
 683  * portTICK_RATE_MS should be used to convert to real time if this is required.\r
 684  * xQueueGenericReceive() will return immediately if the queue is empty and\r
 685  * xTicksToWait is 0.\r
 686  *\r
 687  * @param xJustPeek When set to true, the item received from the queue is not\r
 688  * actually removed from the queue - meaning a subsequent call to\r
 689  * xQueueReceive() will return the same item.  When set to false, the item\r
 690  * being received from the queue is also removed from the queue.\r
 691  *\r
 692  * @return pdTRUE if an item was successfully received from the queue,\r
 693  * otherwise pdFALSE.\r
 694  *\r
 695  * Example usage:\r
 696    <pre>\r
 697  struct AMessage\r
 698  {\r
 699     portCHAR ucMessageID;\r
 700     portCHAR ucData[ 20 ];\r
 701  } xMessage;\r
 702 \r
 703  xQueueHandle xQueue;\r
 704 \r
 705  // Task to create a queue and post a value.\r
 706  void vATask( void *pvParameters )\r
 707  {\r
 708  struct AMessage *pxMessage;\r
 709 \r
 710     // Create a queue capable of containing 10 pointers to AMessage structures.\r
 711     // These should be passed by pointer as they contain a lot of data.\r
 712     xQueue = xQueueCreate( 10, sizeof( struct AMessage * ) );\r
 713     if( xQueue == 0 )\r
 714     {\r
 715         // Failed to create the queue.\r
 716     }\r
 717 \r
 718     // ...\r
 719 \r
 720     // Send a pointer to a struct AMessage object.  Don't block if the\r
 721     // queue is already full.\r
 722     pxMessage = & xMessage;\r
 723     xQueueSend( xQueue, ( void * ) &pxMessage, ( portTickType ) 0 );\r
 724 \r
 725         // ... Rest of task code.\r
 726  }\r
 727 \r
 728  // Task to receive from the queue.\r
 729  void vADifferentTask( void *pvParameters )\r
 730  {\r
 731  struct AMessage *pxRxedMessage;\r
 732 \r
 733     if( xQueue != 0 )\r
 734     {\r
 735         // Receive a message on the created queue.  Block for 10 ticks if a\r
 736         // message is not immediately available.\r
 737         if( xQueueGenericReceive( xQueue, &( pxRxedMessage ), ( portTickType ) 10 ) )\r
 738         {\r
 739             // pcRxedMessage now points to the struct AMessage variable posted\r
 740             // by vATask.\r
 741         }\r
 742     }\r
 743 \r
 744         // ... Rest of task code.\r
 745  }\r
 746  </pre>\r
 747  * \defgroup xQueueReceive xQueueReceive\r
 748  * \ingroup QueueManagement\r
 749  */\r
 750 signed portBASE_TYPE xQueueGenericReceive( xQueueHandle xQueue, void * const pvBuffer, portTickType xTicksToWait, portBASE_TYPE xJustPeek );\r
 751 \r
 752 /**\r
 753  * queue. h\r
 754  * <pre>unsigned portBASE_TYPE uxQueueMessagesWaiting( const xQueueHandle xQueue );</pre>\r
 755  *\r
 756  * Return the number of messages stored in a queue.\r
 757  *\r
 758  * @param xQueue A handle to the queue being queried.\r
 759  *\r
 760  * @return The number of messages available in the queue.\r
 761  *\r
 762  * \page uxQueueMessagesWaiting uxQueueMessagesWaiting\r
 763  * \ingroup QueueManagement\r
 764  */\r
 765 unsigned portBASE_TYPE uxQueueMessagesWaiting( const xQueueHandle xQueue );\r
 766 \r
 767 /**\r
 768  * queue. h\r
 769  * <pre>void vQueueDelete( xQueueHandle xQueue );</pre>\r
 770  *\r
 771  * Delete a queue - freeing all the memory allocated for storing of items\r
 772  * placed on the queue.\r
 773  *\r
 774  * @param xQueue A handle to the queue to be deleted.\r
 775  *\r
 776  * \page vQueueDelete vQueueDelete\r
 777  * \ingroup QueueManagement\r
 778  */\r
 779 void vQueueDelete( xQueueHandle xQueue );\r
 780 \r
 781 /**\r
 782  * queue. h\r
 783  * <pre>\r
 784  portBASE_TYPE xQueueSendToFrontFromISR(\r
 785                                          xQueueHandle pxQueue,\r
 786                                          const void *pvItemToQueue,\r
 787                                          portBASE_TYPE *pxHigherPriorityTaskWoken\r
 788                                       );\r
 789  </pre>\r
 790  *\r
 791  * This is a macro that calls xQueueGenericSendFromISR().\r
 792  *\r
 793  * Post an item to the front of a queue.  It is safe to use this macro from\r
 794  * within an interrupt service routine.\r
 795  *\r
 796  * Items are queued by copy not reference so it is preferable to only\r
 797  * queue small items, especially when called from an ISR.  In most cases\r
 798  * it would be preferable to store a pointer to the item being queued.\r
 799  *\r
 800  * @param xQueue The handle to the queue on which the item is to be posted.\r
 801  *\r
 802  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
 803  * queue.  The size of the items the queue will hold was defined when the\r
 804  * queue was created, so this many bytes will be copied from pvItemToQueue\r
 805  * into the queue storage area.\r
 806  *\r
 807  * @param pxHigherPriorityTaskWoken xQueueSendToFrontFromISR() will set\r
 808  * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task\r
 809  * to unblock, and the unblocked task has a priority higher than the currently\r
 810  * running task.  If xQueueSendToFromFromISR() sets this value to pdTRUE then\r
 811  * a context switch should be requested before the interrupt is exited.\r
 812  *\r
 813  * @return pdTRUE if the data was successfully sent to the queue, otherwise\r
 814  * errQUEUE_FULL.\r
 815  *\r
 816  * Example usage for buffered IO (where the ISR can obtain more than one value\r
 817  * per call):\r
 818    <pre>\r
 819  void vBufferISR( void )\r
 820  {\r
 821  portCHAR cIn;\r
 822  portBASE_TYPE xHigherPrioritTaskWoken;\r
 823 \r
 824     // We have not woken a task at the start of the ISR.\r
 825     xHigherPriorityTaskWoken = pdFALSE;\r
 826 \r
 827     // Loop until the buffer is empty.\r
 828     do\r
 829     {\r
 830         // Obtain a byte from the buffer.\r
 831         cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );                                            \r
 832 \r
 833         // Post the byte.  \r
 834         xQueueSendToFrontFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );\r
 835 \r
 836     } while( portINPUT_BYTE( BUFFER_COUNT ) );\r
 837 \r
 838     // Now the buffer is empty we can switch context if necessary.\r
 839     if( xHigherPriorityTaskWoken )\r
 840     {\r
 841         taskYIELD ();\r
 842     }\r
 843  }\r
 844  </pre>\r
 845  *\r
 846  * \defgroup xQueueSendFromISR xQueueSendFromISR\r
 847  * \ingroup QueueManagement\r
 848  */\r
 849 #define xQueueSendToFrontFromISR( pxQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( pxQueue, pvItemToQueue, pxHigherPriorityTaskWoken, queueSEND_TO_FRONT )\r
 850 \r
 851 \r
 852 /**\r
 853  * queue. h\r
 854  * <pre>\r
 855  portBASE_TYPE xQueueSendToBackFromISR(\r
 856                                          xQueueHandle pxQueue,\r
 857                                          const void *pvItemToQueue,\r
 858                                          portBASE_TYPE *pxHigherPriorityTaskWoken\r
 859                                       );\r
 860  </pre>\r
 861  *\r
 862  * This is a macro that calls xQueueGenericSendFromISR().\r
 863  *\r
 864  * Post an item to the back of a queue.  It is safe to use this macro from\r
 865  * within an interrupt service routine.\r
 866  *\r
 867  * Items are queued by copy not reference so it is preferable to only\r
 868  * queue small items, especially when called from an ISR.  In most cases\r
 869  * it would be preferable to store a pointer to the item being queued.\r
 870  *\r
 871  * @param xQueue The handle to the queue on which the item is to be posted.\r
 872  *\r
 873  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
 874  * queue.  The size of the items the queue will hold was defined when the\r
 875  * queue was created, so this many bytes will be copied from pvItemToQueue\r
 876  * into the queue storage area.\r
 877  *\r
 878  * @param pxHigherPriorityTaskWoken xQueueSendToBackFromISR() will set\r
 879  * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task\r
 880  * to unblock, and the unblocked task has a priority higher than the currently\r
 881  * running task.  If xQueueSendToBackFromISR() sets this value to pdTRUE then\r
 882  * a context switch should be requested before the interrupt is exited.\r
 883  *\r
 884  * @return pdTRUE if the data was successfully sent to the queue, otherwise\r
 885  * errQUEUE_FULL.\r
 886  *\r
 887  * Example usage for buffered IO (where the ISR can obtain more than one value\r
 888  * per call):\r
 889    <pre>\r
 890  void vBufferISR( void )\r
 891  {\r
 892  portCHAR cIn;\r
 893  portBASE_TYPE xHigherPriorityTaskWoken;\r
 894 \r
 895     // We have not woken a task at the start of the ISR.\r
 896     xHigherPriorityTaskWoken = pdFALSE;\r
 897 \r
 898     // Loop until the buffer is empty.\r
 899     do\r
 900     {\r
 901         // Obtain a byte from the buffer.\r
 902         cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );                                            \r
 903 \r
 904         // Post the byte.\r
 905         xQueueSendToBackFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );\r
 906 \r
 907     } while( portINPUT_BYTE( BUFFER_COUNT ) );\r
 908 \r
 909     // Now the buffer is empty we can switch context if necessary.\r
 910     if( xHigherPriorityTaskWoken )\r
 911     {\r
 912         taskYIELD ();\r
 913     }\r
 914  }\r
 915  </pre>\r
 916  *\r
 917  * \defgroup xQueueSendFromISR xQueueSendFromISR\r
 918  * \ingroup QueueManagement\r
 919  */\r
 920 #define xQueueSendToBackFromISR( pxQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( pxQueue, pvItemToQueue, pxHigherPriorityTaskWoken, queueSEND_TO_BACK )\r
 921 \r
 922 /**\r
 923  * queue. h\r
 924  * <pre>\r
 925  portBASE_TYPE xQueueSendFromISR(\r
 926                                      xQueueHandle pxQueue,\r
 927                                      const void *pvItemToQueue,\r
 928                                      portBASE_TYPE *pxHigherPriorityTaskWoken\r
 929                                 );\r
 930  </pre>\r
 931  *\r
 932  * This is a macro that calls xQueueGenericSendFromISR().  It is included\r
 933  * for backward compatibility with versions of FreeRTOS.org that did not\r
 934  * include the xQueueSendToBackFromISR() and xQueueSendToFrontFromISR()\r
 935  * macros.\r
 936  *\r
 937  * Post an item to the back of a queue.  It is safe to use this function from\r
 938  * within an interrupt service routine.\r
 939  *\r
 940  * Items are queued by copy not reference so it is preferable to only\r
 941  * queue small items, especially when called from an ISR.  In most cases\r
 942  * it would be preferable to store a pointer to the item being queued.\r
 943  *\r
 944  * @param xQueue The handle to the queue on which the item is to be posted.\r
 945  *\r
 946  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
 947  * queue.  The size of the items the queue will hold was defined when the\r
 948  * queue was created, so this many bytes will be copied from pvItemToQueue\r
 949  * into the queue storage area.\r
 950  *\r
 951  * @param pxHigherPriorityTaskWoken xQueueSendFromISR() will set\r
 952  * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task\r
 953  * to unblock, and the unblocked task has a priority higher than the currently\r
 954  * running task.  If xQueueSendFromISR() sets this value to pdTRUE then\r
 955  * a context switch should be requested before the interrupt is exited.\r
 956  *\r
 957  * @return pdTRUE if the data was successfully sent to the queue, otherwise\r
 958  * errQUEUE_FULL.\r
 959  *\r
 960  * Example usage for buffered IO (where the ISR can obtain more than one value\r
 961  * per call):\r
 962    <pre>\r
 963  void vBufferISR( void )\r
 964  {\r
 965  portCHAR cIn;\r
 966  portBASE_TYPE xHigherPriorityTaskWoken;\r
 967 \r
 968     // We have not woken a task at the start of the ISR.\r
 969     xHigherPriorityTaskWoken = pdFALSE;\r
 970 \r
 971     // Loop until the buffer is empty.\r
 972     do\r
 973     {\r
 974         // Obtain a byte from the buffer.\r
 975         cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );                                            \r
 976 \r
 977         // Post the byte.  \r
 978         xQueueSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWoken );\r
 979 \r
 980     } while( portINPUT_BYTE( BUFFER_COUNT ) );\r
 981 \r
 982     // Now the buffer is empty we can switch context if necessary.\r
 983     if( xHigherPriorityTaskWoken )\r
 984     {\r
 985         // Actual macro used here is port specific.\r
 986         taskYIELD_FROM_ISR ();\r
 987     }\r
 988  }\r
 989  </pre>\r
 990  *\r
 991  * \defgroup xQueueSendFromISR xQueueSendFromISR\r
 992  * \ingroup QueueManagement\r
 993  */\r
 994 #define xQueueSendFromISR( pxQueue, pvItemToQueue, pxHigherPriorityTaskWoken ) xQueueGenericSendFromISR( pxQueue, pvItemToQueue, pxHigherPriorityTaskWoken, queueSEND_TO_BACK )\r
 995 \r
 996 /**\r
 997  * queue. h\r
 998  * <pre>\r
 999  portBASE_TYPE xQueueGenericSendFromISR(\r
1000                                            xQueueHandle pxQueue,\r
1001                                            const void *pvItemToQueue,\r
1002                                            portBASE_TYPE *pxHigherPriorityTaskWoken,\r
1003                                                                                    portBASE_TYPE xCopyPosition\r
1004                                        );\r
1005  </pre>\r
1006  *\r
1007  * It is preferred that the macros xQueueSendFromISR(),\r
1008  * xQueueSendToFrontFromISR() and xQueueSendToBackFromISR() be used in place\r
1009  * of calling this function directly.\r
1010  *\r
1011  * Post an item on a queue.  It is safe to use this function from within an\r
1012  * interrupt service routine.\r
1013  *\r
1014  * Items are queued by copy not reference so it is preferable to only\r
1015  * queue small items, especially when called from an ISR.  In most cases\r
1016  * it would be preferable to store a pointer to the item being queued.\r
1017  *\r
1018  * @param xQueue The handle to the queue on which the item is to be posted.\r
1019  *\r
1020  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
1021  * queue.  The size of the items the queue will hold was defined when the\r
1022  * queue was created, so this many bytes will be copied from pvItemToQueue\r
1023  * into the queue storage area.\r
1024  *\r
1025  * @param pxHigherPriorityTaskWoken xQueueGenericSendFromISR() will set\r
1026  * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task\r
1027  * to unblock, and the unblocked task has a priority higher than the currently\r
1028  * running task.  If xQueueGenericSendFromISR() sets this value to pdTRUE then\r
1029  * a context switch should be requested before the interrupt is exited.\r
1030  *\r
1031  * @param xCopyPosition Can take the value queueSEND_TO_BACK to place the\r
1032  * item at the back of the queue, or queueSEND_TO_FRONT to place the item\r
1033  * at the front of the queue (for high priority messages).\r
1034  *\r
1035  * @return pdTRUE if the data was successfully sent to the queue, otherwise\r
1036  * errQUEUE_FULL.\r
1037  *\r
1038  * Example usage for buffered IO (where the ISR can obtain more than one value\r
1039  * per call):\r
1040    <pre>\r
1041  void vBufferISR( void )\r
1042  {\r
1043  portCHAR cIn;\r
1044  portBASE_TYPE xHigherPriorityTaskWokenByPost;\r
1045 \r
1046     // We have not woken a task at the start of the ISR.\r
1047     xHigherPriorityTaskWokenByPost = pdFALSE;\r
1048 \r
1049     // Loop until the buffer is empty.\r
1050     do\r
1051     {\r
1052         // Obtain a byte from the buffer.\r
1053         cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );                                            \r
1054 \r
1055         // Post each byte.\r
1056         xQueueGenericSendFromISR( xRxQueue, &cIn, &xHigherPriorityTaskWokenByPost, queueSEND_TO_BACK );\r
1057 \r
1058     } while( portINPUT_BYTE( BUFFER_COUNT ) );\r
1059 \r
1060     // Now the buffer is empty we can switch context if necessary.  Note that the\r
1061     // name of the yield function required is port specific.\r
1062     if( xHigherPriorityTaskWokenByPost )\r
1063     {\r
1064         taskYIELD_YIELD_FROM_ISR();\r
1065     }\r
1066  }\r
1067  </pre>\r
1068  *\r
1069  * \defgroup xQueueSendFromISR xQueueSendFromISR\r
1070  * \ingroup QueueManagement\r
1071  */\r
1072 signed portBASE_TYPE xQueueGenericSendFromISR( xQueueHandle pxQueue, const void * const pvItemToQueue, signed portBASE_TYPE *pxHigherPriorityTaskWoken, portBASE_TYPE xCopyPosition );\r
1073 \r
1074 /**\r
1075  * queue. h\r
1076  * <pre>\r
1077  portBASE_TYPE xQueueReceiveFromISR(\r
1078                                        xQueueHandle pxQueue,\r
1079                                        void *pvBuffer,\r
1080                                        portBASE_TYPE *pxTaskWoken\r
1081                                    );\r
1082  * </pre>\r
1083  *\r
1084  * Receive an item from a queue.  It is safe to use this function from within an\r
1085  * interrupt service routine.\r
1086  *\r
1087  * @param pxQueue The handle to the queue from which the item is to be\r
1088  * received.\r
1089  *\r
1090  * @param pvBuffer Pointer to the buffer into which the received item will\r
1091  * be copied.\r
1092  *\r
1093  * @param pxTaskWoken A task may be blocked waiting for space to become\r
1094  * available on the queue.  If xQueueReceiveFromISR causes such a task to\r
1095  * unblock *pxTaskWoken will get set to pdTRUE, otherwise *pxTaskWoken will\r
1096  * remain unchanged.\r
1097  *\r
1098  * @return pdTRUE if an item was successfully received from the queue,\r
1099  * otherwise pdFALSE.\r
1100  *\r
1101  * Example usage:\r
1102    <pre>\r
1103 \r
1104  xQueueHandle xQueue;\r
1105 \r
1106  // Function to create a queue and post some values.\r
1107  void vAFunction( void *pvParameters )\r
1108  {\r
1109  portCHAR cValueToPost;\r
1110  const portTickType xBlockTime = ( portTickType )0xff;\r
1111 \r
1112     // Create a queue capable of containing 10 characters.\r
1113     xQueue = xQueueCreate( 10, sizeof( portCHAR ) );\r
1114     if( xQueue == 0 )\r
1115     {\r
1116         // Failed to create the queue.\r
1117     }\r
1118 \r
1119     // ...\r
1120 \r
1121     // Post some characters that will be used within an ISR.  If the queue\r
1122     // is full then this task will block for xBlockTime ticks.\r
1123     cValueToPost = 'a';\r
1124     xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );\r
1125     cValueToPost = 'b';\r
1126     xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );\r
1127 \r
1128     // ... keep posting characters ... this task may block when the queue\r
1129     // becomes full.\r
1130 \r
1131     cValueToPost = 'c';\r
1132     xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );\r
1133  }\r
1134 \r
1135  // ISR that outputs all the characters received on the queue.\r
1136  void vISR_Routine( void )\r
1137  {\r
1138  portBASE_TYPE xTaskWokenByReceive = pdFALSE;\r
1139  portCHAR cRxedChar;\r
1140 \r
1141     while( xQueueReceiveFromISR( xQueue, ( void * ) &cRxedChar, &xTaskWokenByReceive) )\r
1142     {\r
1143         // A character was received.  Output the character now.\r
1144         vOutputCharacter( cRxedChar );\r
1145 \r
1146         // If removing the character from the queue woke the task that was\r
1147         // posting onto the queue cTaskWokenByReceive will have been set to\r
1148         // pdTRUE.  No matter how many times this loop iterates only one\r
1149         // task will be woken.\r
1150     }\r
1151 \r
1152     if( cTaskWokenByPost != ( portCHAR ) pdFALSE;\r
1153     {\r
1154         taskYIELD ();\r
1155     }\r
1156  }\r
1157  </pre>\r
1158  * \defgroup xQueueReceiveFromISR xQueueReceiveFromISR\r
1159  * \ingroup QueueManagement\r
1160  */\r
1161 signed portBASE_TYPE xQueueReceiveFromISR( xQueueHandle pxQueue, void * const pvBuffer, signed portBASE_TYPE *pxTaskWoken );\r
1162 \r
1163 /*\r
1164  * Utilities to query queue that are safe to use from an ISR.  These utilities\r
1165  * should be used only from witin an ISR, or within a critical section.\r
1166  */\r
1167 signed portBASE_TYPE xQueueIsQueueEmptyFromISR( const xQueueHandle pxQueue );\r
1168 signed portBASE_TYPE xQueueIsQueueFullFromISR( const xQueueHandle pxQueue );\r
1169 unsigned portBASE_TYPE uxQueueMessagesWaitingFromISR( const xQueueHandle pxQueue );\r
1170 \r
1171 \r
1172 /* \r
1173  * xQueueAltGenericSend() is an alternative version of xQueueGenericSend().\r
1174  * Likewise xQueueAltGenericReceive() is an alternative version of\r
1175  * xQueueGenericReceive().\r
1176  *\r
1177  * The source code that implements the alternative (Alt) API is much \r
1178  * simpler      because it executes everything from within a critical section.  \r
1179  * This is      the approach taken by many other RTOSes, but FreeRTOS.org has the \r
1180  * preferred fully featured API too.  The fully featured API has more \r
1181  * complex      code that takes longer to execute, but makes much less use of \r
1182  * critical sections.  Therefore the alternative API sacrifices interrupt \r
1183  * responsiveness to gain execution speed, whereas the fully featured API\r
1184  * sacrifices execution speed to ensure better interrupt responsiveness.\r
1185  */\r
1186 signed portBASE_TYPE xQueueAltGenericSend( xQueueHandle pxQueue, const void * const pvItemToQueue, portTickType xTicksToWait, portBASE_TYPE xCopyPosition );\r
1187 signed portBASE_TYPE xQueueAltGenericReceive( xQueueHandle pxQueue, void * const pvBuffer, portTickType xTicksToWait, portBASE_TYPE xJustPeeking );\r
1188 #define xQueueAltSendToFront( xQueue, pvItemToQueue, xTicksToWait ) xQueueAltGenericSend( xQueue, pvItemToQueue, xTicksToWait, queueSEND_TO_FRONT )\r
1189 #define xQueueAltSendToBack( xQueue, pvItemToQueue, xTicksToWait ) xQueueAltGenericSend( xQueue, pvItemToQueue, xTicksToWait, queueSEND_TO_BACK )\r
1190 #define xQueueAltReceive( xQueue, pvBuffer, xTicksToWait ) xQueueAltGenericReceive( xQueue, pvBuffer, xTicksToWait, pdFALSE )\r
1191 #define xQueueAltPeek( xQueue, pvBuffer, xTicksToWait ) xQueueAltGenericReceive( xQueue, pvBuffer, xTicksToWait, pdTRUE )\r
1192 \r
1193 /*\r
1194  * The functions defined above are for passing data to and from tasks.  The\r
1195  * functions below are the equivalents for passing data to and from\r
1196  * co-routines.\r
1197  *\r
1198  * These functions are called from the co-routine macro implementation and\r
1199  * should not be called directly from application code.  Instead use the macro\r
1200  * wrappers defined within croutine.h.\r
1201  */\r
1202 signed portBASE_TYPE xQueueCRSendFromISR( xQueueHandle pxQueue, const void *pvItemToQueue, signed portBASE_TYPE xCoRoutinePreviouslyWoken );\r
1203 signed portBASE_TYPE xQueueCRReceiveFromISR( xQueueHandle pxQueue, void *pvBuffer, signed portBASE_TYPE *pxTaskWoken );\r
1204 signed portBASE_TYPE xQueueCRSend( xQueueHandle pxQueue, const void *pvItemToQueue, portTickType xTicksToWait );\r
1205 signed portBASE_TYPE xQueueCRReceive( xQueueHandle pxQueue, void *pvBuffer, portTickType xTicksToWait );\r
1206 \r
1207 /*\r
1208  * For internal use only.  Use xSemaphoreCreateMutex() or\r
1209  * xSemaphoreCreateCounting() instead of calling these functions directly.\r
1210  */\r
1211 xQueueHandle xQueueCreateMutex( void );\r
1212 xQueueHandle xQueueCreateCountingSemaphore( unsigned portBASE_TYPE uxCountValue, unsigned portBASE_TYPE uxInitialCount );\r
1213 \r
1214 /*\r
1215  * For internal use only.  Use xSemaphoreTakeMutexRecursive() or\r
1216  * xSemaphoreGiveMutexRecursive() instead of calling these functions directly.\r
1217  */\r
1218 portBASE_TYPE xQueueTakeMutexRecursive( xQueueHandle xMutex, portTickType xBlockTime );\r
1219 portBASE_TYPE xQueueGiveMutexRecursive( xQueueHandle xMutex );\r
1220 \r
1221 /*\r
1222  * The registry is provided as a means for kernel aware debuggers to\r
1223  * locate queues, semaphores and mutexes.  Call vQueueAddToRegistry() add\r
1224  * a queue, semaphore or mutex handle to the registry if you want the handle \r
1225  * to be available to a kernel aware debugger.  If you are not using a kernel \r
1226  * aware debugger then this function can be ignored.\r
1227  *\r
1228  * configQUEUE_REGISTRY_SIZE defines the maximum number of handles the\r
1229  * registry can hold.  configQUEUE_REGISTRY_SIZE must be greater than 0 \r
1230  * within FreeRTOSConfig.h for the registry to be available.  Its value\r
1231  * does not effect the number of queues, semaphores and mutexes that can be \r
1232  * created - just the number that the registry can hold.\r
1233  *\r
1234  * @param xQueue The handle of the queue being added to the registry.  This\r
1235  * is the handle returned by a call to xQueueCreate().  Semaphore and mutex\r
1236  * handles can also be passed in here.\r
1237  *\r
1238  * @param pcName The name to be associated with the handle.  This is the\r
1239  * name that the kernel aware debugger will display.\r
1240  */\r
1241 #if configQUEUE_REGISTRY_SIZE > 0\r
1242         void vQueueAddToRegistry( xQueueHandle xQueue, signed portCHAR *pcName );\r
1243 #endif\r
1244 \r
1245 \r
1246 \r
1247 \r
1248 #ifdef __cplusplus\r
1249 }\r
1250 #endif\r
1251 \r
1252 #endif /* QUEUE_H */\r
1253 \r