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

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