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, const 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 cTaskPreviouslyWoken This is included so an ISR can post onto\r
 793  * the same queue multiple times from a single interrupt.  The first call\r
 794  * should always pass in pdFALSE.  Subsequent calls should pass in\r
 795  * the value returned from the previous call.  See the file serial .c in the\r
 796  * PC port for a good example of this mechanism.\r
 797  *\r
 798  * @return pdTRUE if a task was woken by posting onto the queue.  This is\r
 799  * used by the ISR to determine if a context switch may be required following\r
 800  * the ISR.\r
 801  *\r
 802  * Example usage for buffered IO (where the ISR can obtain more than one value\r
 803  * per call):\r
 804    <pre>\r
 805  void vBufferISR( void )\r
 806  {\r
 807  portCHAR cIn;\r
 808  portBASE_TYPE xTaskWokenByPost;\r
 809 \r
 810     // We have not woken a task at the start of the ISR.\r
 811     cTaskWokenByPost = pdFALSE;\r
 812 \r
 813     // Loop until the buffer is empty.\r
 814     do\r
 815     {\r
 816         // Obtain a byte from the buffer.\r
 817         cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );                                            \r
 818 \r
 819         // Post the byte.  The first time round the loop cTaskWokenByPost\r
 820         // will be pdFALSE.  If the queue send causes a task to wake we do\r
 821         // not want the task to run until we have finished the ISR, so\r
 822         // xQueueSendFromISR does not cause a context switch.  Also we\r
 823         // don't want subsequent posts to wake any other tasks, so we store\r
 824         // the return value back into cTaskWokenByPost so xQueueSendFromISR\r
 825         // knows not to wake any task the next iteration of the loop.\r
 826         xTaskWokenByPost = xQueueSendToFrontFromISR( xRxQueue, &cIn, cTaskWokenByPost );\r
 827 \r
 828     } while( portINPUT_BYTE( BUFFER_COUNT ) );\r
 829 \r
 830     // Now the buffer is empty we can switch context if necessary.\r
 831     if( cTaskWokenByPost )\r
 832     {\r
 833         taskYIELD ();\r
 834     }\r
 835  }\r
 836  </pre>\r
 837  *\r
 838  * \defgroup xQueueSendFromISR xQueueSendFromISR\r
 839  * \ingroup QueueManagement\r
 840  */\r
 841 #define xQueueSendToFrontFromISR( pxQueue, pvItemToQueue, xTaskPreviouslyWoken ) xQueueGenericSendFromISR( pxQueue, pvItemToQueue, xTaskPreviouslyWoken, queueSEND_TO_FRONT )\r
 842 \r
 843 \r
 844 /**\r
 845  * queue. h\r
 846  * <pre>\r
 847  portBASE_TYPE xQueueSendToBackFromISR(\r
 848                                          xQueueHandle pxQueue,\r
 849                                          const void *pvItemToQueue,\r
 850                                          portBASE_TYPE xTaskPreviouslyWoken\r
 851                                       );\r
 852  </pre>\r
 853  *\r
 854  * This is a macro that calls xQueueGenericSendFromISR().\r
 855  *\r
 856  * Post an item to the back of a queue.  It is safe to use this macro from\r
 857  * within an interrupt service routine.\r
 858  *\r
 859  * Items are queued by copy not reference so it is preferable to only\r
 860  * queue small items, especially when called from an ISR.  In most cases\r
 861  * it would be preferable to store a pointer to the item being queued.\r
 862  *\r
 863  * @param xQueue The handle to the queue on which the item is to be posted.\r
 864  *\r
 865  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
 866  * queue.  The size of the items the queue will hold was defined when the\r
 867  * queue was created, so this many bytes will be copied from pvItemToQueue\r
 868  * into the queue storage area.\r
 869  *\r
 870  * @param cTaskPreviouslyWoken This is included so an ISR can post onto\r
 871  * the same queue multiple times from a single interrupt.  The first call\r
 872  * should always pass in pdFALSE.  Subsequent calls should pass in\r
 873  * the value returned from the previous call.  See the file serial .c in the\r
 874  * PC port for a good example of this mechanism.\r
 875  *\r
 876  * @return pdTRUE if a task was woken by posting onto the queue.  This is\r
 877  * used by the ISR to determine if a context switch may be required following\r
 878  * the ISR.\r
 879  *\r
 880  * Example usage for buffered IO (where the ISR can obtain more than one value\r
 881  * per call):\r
 882    <pre>\r
 883  void vBufferISR( void )\r
 884  {\r
 885  portCHAR cIn;\r
 886  portBASE_TYPE xTaskWokenByPost;\r
 887 \r
 888     // We have not woken a task at the start of the ISR.\r
 889     cTaskWokenByPost = pdFALSE;\r
 890 \r
 891     // Loop until the buffer is empty.\r
 892     do\r
 893     {\r
 894         // Obtain a byte from the buffer.\r
 895         cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );                                            \r
 896 \r
 897         // Post the byte.  The first time round the loop cTaskWokenByPost\r
 898         // will be pdFALSE.  If the queue send causes a task to wake we do\r
 899         // not want the task to run until we have finished the ISR, so\r
 900         // xQueueSendFromISR does not cause a context switch.  Also we\r
 901         // don't want subsequent posts to wake any other tasks, so we store\r
 902         // the return value back into cTaskWokenByPost so xQueueSendFromISR\r
 903         // knows not to wake any task the next iteration of the loop.\r
 904         xTaskWokenByPost = xQueueSendToBackFromISR( xRxQueue, &cIn, cTaskWokenByPost );\r
 905 \r
 906     } while( portINPUT_BYTE( BUFFER_COUNT ) );\r
 907 \r
 908     // Now the buffer is empty we can switch context if necessary.\r
 909     if( cTaskWokenByPost )\r
 910     {\r
 911         taskYIELD ();\r
 912     }\r
 913  }\r
 914  </pre>\r
 915  *\r
 916  * \defgroup xQueueSendFromISR xQueueSendFromISR\r
 917  * \ingroup QueueManagement\r
 918  */\r
 919 #define xQueueSendToBackFromISR( pxQueue, pvItemToQueue, xTaskPreviouslyWoken ) xQueueGenericSendFromISR( pxQueue, pvItemToQueue, xTaskPreviouslyWoken, queueSEND_TO_BACK )\r
 920 \r
 921 /**\r
 922  * queue. h\r
 923  * <pre>\r
 924  portBASE_TYPE xQueueSendFromISR(\r
 925                                      xQueueHandle pxQueue,\r
 926                                      const void *pvItemToQueue,\r
 927                                      portBASE_TYPE xTaskPreviouslyWoken\r
 928                                 );\r
 929  </pre>\r
 930  *\r
 931  * This is a macro that calls xQueueGenericSendFromISR().  It is included\r
 932  * for backward compatibility with versions of FreeRTOS.org that did not\r
 933  * include the xQueueSendToBackFromISR() and xQueueSendToFrontFromISR()\r
 934  * macros.\r
 935  *\r
 936  * Post an item to the back of a queue.  It is safe to use this function from\r
 937  * within an interrupt service routine.\r
 938  *\r
 939  * Items are queued by copy not reference so it is preferable to only\r
 940  * queue small items, especially when called from an ISR.  In most cases\r
 941  * it would be preferable to store a pointer to the item being queued.\r
 942  *\r
 943  * @param xQueue The handle to the queue on which the item is to be posted.\r
 944  *\r
 945  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
 946  * queue.  The size of the items the queue will hold was defined when the\r
 947  * queue was created, so this many bytes will be copied from pvItemToQueue\r
 948  * into the queue storage area.\r
 949  *\r
 950  * @param cTaskPreviouslyWoken This is included so an ISR can post onto\r
 951  * the same queue multiple times from a single interrupt.  The first call\r
 952  * should always pass in pdFALSE.  Subsequent calls should pass in\r
 953  * the value returned from the previous call.  See the file serial .c in the\r
 954  * PC port for a good example of this mechanism.\r
 955  *\r
 956  * @return pdTRUE if a task was woken by posting onto the queue.  This is\r
 957  * used by the ISR to determine if a context switch may be required following\r
 958  * the ISR.\r
 959  *\r
 960  * Example usage for buffered IO (where the ISR can obtain more than one value\r
 961  * per call):\r
 962    <pre>\r
 963  void vBufferISR( void )\r
 964  {\r
 965  portCHAR cIn;\r
 966  portBASE_TYPE xTaskWokenByPost;\r
 967 \r
 968     // We have not woken a task at the start of the ISR.\r
 969     cTaskWokenByPost = pdFALSE;\r
 970 \r
 971     // Loop until the buffer is empty.\r
 972     do\r
 973     {\r
 974         // Obtain a byte from the buffer.\r
 975         cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );                                            \r
 976 \r
 977         // Post the byte.  The first time round the loop cTaskWokenByPost\r
 978         // will be pdFALSE.  If the queue send causes a task to wake we do\r
 979         // not want the task to run until we have finished the ISR, so\r
 980         // xQueueSendFromISR does not cause a context switch.  Also we\r
 981         // don't want subsequent posts to wake any other tasks, so we store\r
 982         // the return value back into cTaskWokenByPost so xQueueSendFromISR\r
 983         // knows not to wake any task the next iteration of the loop.\r
 984         xTaskWokenByPost = xQueueSendFromISR( xRxQueue, &cIn, cTaskWokenByPost );\r
 985 \r
 986     } while( portINPUT_BYTE( BUFFER_COUNT ) );\r
 987 \r
 988     // Now the buffer is empty we can switch context if necessary.\r
 989     if( cTaskWokenByPost )\r
 990     {\r
 991         taskYIELD ();\r
 992     }\r
 993  }\r
 994  </pre>\r
 995  *\r
 996  * \defgroup xQueueSendFromISR xQueueSendFromISR\r
 997  * \ingroup QueueManagement\r
 998  */\r
 999 #define xQueueSendFromISR( pxQueue, pvItemToQueue, xTaskPreviouslyWoken ) xQueueGenericSendFromISR( pxQueue, pvItemToQueue, xTaskPreviouslyWoken, queueSEND_TO_BACK )\r
1000 \r
1001 /**\r
1002  * queue. h\r
1003  * <pre>\r
1004  portBASE_TYPE xQueueGenericSendFromISR(\r
1005                                            xQueueHandle pxQueue,\r
1006                                            const void *pvItemToQueue,\r
1007                                            portBASE_TYPE xTaskPreviouslyWoken\r
1008                                                                                    portBASE_TYPE xCopyPosition\r
1009                                        );\r
1010  </pre>\r
1011  *\r
1012  * It is preferred that the macros xQueueSendFromISR(),\r
1013  * xQueueSendToFrontFromISR() and xQueueSendToBackFromISR() be used in place\r
1014  * of calling this function directly.\r
1015  *\r
1016  * Post an item on a queue.  It is safe to use this function from within an\r
1017  * interrupt service routine.\r
1018  *\r
1019  * Items are queued by copy not reference so it is preferable to only\r
1020  * queue small items, especially when called from an ISR.  In most cases\r
1021  * it would be preferable to store a pointer to the item being queued.\r
1022  *\r
1023  * @param xQueue The handle to the queue on which the item is to be posted.\r
1024  *\r
1025  * @param pvItemToQueue A pointer to the item that is to be placed on the\r
1026  * queue.  The size of the items the queue will hold was defined when the\r
1027  * queue was created, so this many bytes will be copied from pvItemToQueue\r
1028  * into the queue storage area.\r
1029  *\r
1030  * @param cTaskPreviouslyWoken This is included so an ISR can post onto\r
1031  * the same queue multiple times from a single interrupt.  The first call\r
1032  * should always pass in pdFALSE.  Subsequent calls should pass in\r
1033  * the value returned from the previous call.  See the file serial .c in the\r
1034  * PC port for a good example of this mechanism.\r
1035  *\r
1036  * @param xCopyPosition Can take the value queueSEND_TO_BACK to place the\r
1037  * item at the back of the queue, or queueSEND_TO_FRONT to place the item\r
1038  * at the front of the queue (for high priority messages).\r
1039  *\r
1040  * @return pdTRUE if a task was woken by posting onto the queue.  This is\r
1041  * used by the ISR to determine if a context switch may be required following\r
1042  * the ISR.\r
1043  *\r
1044  * Example usage for buffered IO (where the ISR can obtain more than one value\r
1045  * per call):\r
1046    <pre>\r
1047  void vBufferISR( void )\r
1048  {\r
1049  portCHAR cIn;\r
1050  portBASE_TYPE xTaskWokenByPost;\r
1051 \r
1052     // We have not woken a task at the start of the ISR.\r
1053     cTaskWokenByPost = pdFALSE;\r
1054 \r
1055     // Loop until the buffer is empty.\r
1056     do\r
1057     {\r
1058         // Obtain a byte from the buffer.\r
1059         cIn = portINPUT_BYTE( RX_REGISTER_ADDRESS );                                            \r
1060 \r
1061         // Post the byte.  The first time round the loop cTaskWokenByPost\r
1062         // will be pdFALSE.  If the queue send causes a task to wake we do\r
1063         // not want the task to run until we have finished the ISR, so\r
1064         // xQueueSendFromISR does not cause a context switch.  Also we\r
1065         // don't want subsequent posts to wake any other tasks, so we store\r
1066         // the return value back into cTaskWokenByPost so xQueueSendFromISR\r
1067         // knows not to wake any task the next iteration of the loop.\r
1068         xTaskWokenByPost = xQueueGenericSendFromISR( xRxQueue, &cIn, cTaskWokenByPost, queueSEND_TO_BACK );\r
1069 \r
1070     } while( portINPUT_BYTE( BUFFER_COUNT ) );\r
1071 \r
1072     // Now the buffer is empty we can switch context if necessary.\r
1073     if( cTaskWokenByPost )\r
1074     {\r
1075         taskYIELD ();\r
1076     }\r
1077  }\r
1078  </pre>\r
1079  *\r
1080  * \defgroup xQueueSendFromISR xQueueSendFromISR\r
1081  * \ingroup QueueManagement\r
1082  */\r
1083 signed portBASE_TYPE xQueueGenericSendFromISR( xQueueHandle pxQueue, const void * const pvItemToQueue, signed portBASE_TYPE xTaskPreviouslyWoken, portBASE_TYPE xCopyPosition );\r
1084 \r
1085 /**\r
1086  * queue. h\r
1087  * <pre>\r
1088  portBASE_TYPE xQueueReceiveFromISR(\r
1089                                        xQueueHandle pxQueue,\r
1090                                        void *pvBuffer,\r
1091                                        portBASE_TYPE *pxTaskWoken\r
1092                                    );\r
1093  * </pre>\r
1094  *\r
1095  * Receive an item from a queue.  It is safe to use this function from within an\r
1096  * interrupt service routine.\r
1097  *\r
1098  * @param pxQueue The handle to the queue from which the item is to be\r
1099  * received.\r
1100  *\r
1101  * @param pvBuffer Pointer to the buffer into which the received item will\r
1102  * be copied.\r
1103  *\r
1104  * @param pxTaskWoken A task may be blocked waiting for space to become\r
1105  * available on the queue.  If xQueueReceiveFromISR causes such a task to\r
1106  * unblock *pxTaskWoken will get set to pdTRUE, otherwise *pxTaskWoken will\r
1107  * remain unchanged.\r
1108  *\r
1109  * @return pdTRUE if an item was successfully received from the queue,\r
1110  * otherwise pdFALSE.\r
1111  *\r
1112  * Example usage:\r
1113    <pre>\r
1114 \r
1115  xQueueHandle xQueue;\r
1116 \r
1117  // Function to create a queue and post some values.\r
1118  void vAFunction( void *pvParameters )\r
1119  {\r
1120  portCHAR cValueToPost;\r
1121  const portTickType xBlockTime = ( portTickType )0xff;\r
1122 \r
1123     // Create a queue capable of containing 10 characters.\r
1124     xQueue = xQueueCreate( 10, sizeof( portCHAR ) );\r
1125     if( xQueue == 0 )\r
1126     {\r
1127         // Failed to create the queue.\r
1128     }\r
1129 \r
1130     // ...\r
1131 \r
1132     // Post some characters that will be used within an ISR.  If the queue\r
1133     // is full then this task will block for xBlockTime ticks.\r
1134     cValueToPost = 'a';\r
1135     xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );\r
1136     cValueToPost = 'b';\r
1137     xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );\r
1138 \r
1139     // ... keep posting characters ... this task may block when the queue\r
1140     // becomes full.\r
1141 \r
1142     cValueToPost = 'c';\r
1143     xQueueSend( xQueue, ( void * ) &cValueToPost, xBlockTime );\r
1144  }\r
1145 \r
1146  // ISR that outputs all the characters received on the queue.\r
1147  void vISR_Routine( void )\r
1148  {\r
1149  portBASE_TYPE xTaskWokenByReceive = pdFALSE;\r
1150  portCHAR cRxedChar;\r
1151 \r
1152     while( xQueueReceiveFromISR( xQueue, ( void * ) &cRxedChar, &xTaskWokenByReceive) )\r
1153     {\r
1154         // A character was received.  Output the character now.\r
1155         vOutputCharacter( cRxedChar );\r
1156 \r
1157         // If removing the character from the queue woke the task that was\r
1158         // posting onto the queue cTaskWokenByReceive will have been set to\r
1159         // pdTRUE.  No matter how many times this loop iterates only one\r
1160         // task will be woken.\r
1161     }\r
1162 \r
1163     if( cTaskWokenByPost != ( portCHAR ) pdFALSE;\r
1164     {\r
1165         taskYIELD ();\r
1166     }\r
1167  }\r
1168  </pre>\r
1169  * \defgroup xQueueReceiveFromISR xQueueReceiveFromISR\r
1170  * \ingroup QueueManagement\r
1171  */\r
1172 signed portBASE_TYPE xQueueReceiveFromISR( xQueueHandle pxQueue, const void * const pvBuffer, signed portBASE_TYPE *pxTaskWoken );\r
1173 \r
1174 /*\r
1175  * Utilities to query queue that are safe to use from an ISR.  These utilities\r
1176  * should be used only from witin an ISR, or within a critical section.\r
1177  */\r
1178 signed portBASE_TYPE xQueueIsQueueEmptyFromISR( const xQueueHandle pxQueue );\r
1179 signed portBASE_TYPE xQueueIsQueueFullFromISR( const xQueueHandle pxQueue );\r
1180 unsigned portBASE_TYPE uxQueueMessagesWaitingFromISR( const xQueueHandle pxQueue );\r
1181 \r
1182 \r
1183 /* \r
1184  * xQueueAltGenericSend() is an alternative version of xQueueGenericSend().\r
1185  * Likewise xQueueAltGenericReceive() is an alternative version of\r
1186  * xQueueGenericReceive().\r
1187  *\r
1188  * The source code that implements the alternative (Alt) API is much \r
1189  * simpler      because it executes everything from within a critical section.  \r
1190  * This is      the approach taken by many other RTOSes, but FreeRTOS.org has the \r
1191  * preferred fully featured API too.  The fully featured API has more \r
1192  * complex      code that takes longer to execute, but makes much less use of \r
1193  * critical sections.  Therefore the alternative API sacrifices interrupt \r
1194  * responsiveness to gain execution speed, whereas the fully featured API\r
1195  * sacrifices execution speed to ensure better interrupt responsiveness.\r
1196  */\r
1197 signed portBASE_TYPE xQueueAltGenericSend( xQueueHandle pxQueue, const void * const pvItemToQueue, portTickType xTicksToWait, portBASE_TYPE xCopyPosition );\r
1198 signed portBASE_TYPE xQueueAltGenericReceive( xQueueHandle pxQueue, const void * const pvBuffer, portTickType xTicksToWait, portBASE_TYPE xJustPeeking );\r
1199 #define xQueueAltSendToFront( xQueue, pvItemToQueue, xTicksToWait ) xQueueAltGenericSend( xQueue, pvItemToQueue, xTicksToWait, queueSEND_TO_FRONT )\r
1200 #define xQueueAltSendToBack( xQueue, pvItemToQueue, xTicksToWait ) xQueueAltGenericSend( xQueue, pvItemToQueue, xTicksToWait, queueSEND_TO_BACK )\r
1201 #define xQueueAltReceive( xQueue, pvBuffer, xTicksToWait ) xQueueAltGenericReceive( xQueue, pvBuffer, xTicksToWait, pdFALSE )\r
1202 #define xQueueAltPeek( xQueue, pvBuffer, xTicksToWait ) xQueueAltGenericReceive( xQueue, pvBuffer, xTicksToWait, pdTRUE )\r
1203 \r
1204 /*\r
1205  * The functions defined above are for passing data to and from tasks.  The\r
1206  * functions below are the equivalents for passing data to and from\r
1207  * co-routines.\r
1208  *\r
1209  * These functions are called from the co-routine macro implementation and\r
1210  * should not be called directly from application code.  Instead use the macro\r
1211  * wrappers defined within croutine.h.\r
1212  */\r
1213 signed portBASE_TYPE xQueueCRSendFromISR( xQueueHandle pxQueue, const void *pvItemToQueue, signed portBASE_TYPE xCoRoutinePreviouslyWoken );\r
1214 signed portBASE_TYPE xQueueCRReceiveFromISR( xQueueHandle pxQueue, void *pvBuffer, signed portBASE_TYPE *pxTaskWoken );\r
1215 signed portBASE_TYPE xQueueCRSend( xQueueHandle pxQueue, const void *pvItemToQueue, portTickType xTicksToWait );\r
1216 signed portBASE_TYPE xQueueCRReceive( xQueueHandle pxQueue, void *pvBuffer, portTickType xTicksToWait );\r
1217 \r
1218 /*\r
1219  * For internal use only.  Use xSemaphoreCreateMutex() or\r
1220  * xSemaphoreCreateCounting() instead of calling these functions directly.\r
1221  */\r
1222 xQueueHandle xQueueCreateMutex( void );\r
1223 xQueueHandle xQueueCreateCountingSemaphore( unsigned portBASE_TYPE uxCountValue, unsigned portBASE_TYPE uxInitialCount );\r
1224 \r
1225 /*\r
1226  * For internal use only.  Use xSemaphoreTakeMutexRecursive() or\r
1227  * xSemaphoreGiveMutexRecursive() instead of calling these functions directly.\r
1228  */\r
1229 portBASE_TYPE xQueueTakeMutexRecursive( xQueueHandle xMutex, portTickType xBlockTime );\r
1230 portBASE_TYPE xQueueGiveMutexRecursive( xQueueHandle xMutex );\r
1231 \r
1232 \r
1233 #ifdef __cplusplus\r
1234 }\r
1235 #endif\r
1236 \r
1237 #endif /* QUEUE_H */\r
1238 \r