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

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