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

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