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