Lines Matching full:the
8 * this software and associated documentation files (the "Software"), to deal in
9 * the Software without restriction, including without limitation the rights to
11 * the Software, and to permit persons to whom the Software is furnished to do so,
12 * subject to the following conditions:
14 * The above copyright notice and this permission notice shall be included in all
15 * copies or substantial portions of the Software.
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
19 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
22 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
61 * Queue sets can contain both queues and semaphores, so the
89 * Creates a new queue instance, and returns a handle by which the new queue
92 * Internally, within the FreeRTOS implementation, queues use two blocks of
93 * memory. The first block is used to hold the queue's data structures. The
94 * second block is used to hold items placed into the queue. If a queue is
96 * dynamically allocated inside the xQueueCreate() function. (see
98 * xQueueCreateStatic() then the application writer must provide the memory that
99 * will get used by the queue. xQueueCreateStatic() therefore allows a queue to
104 * @param uxQueueLength The maximum number of items that the queue can contain.
106 * @param uxItemSize The number of bytes each item in the queue will require.
107 * Items are queued by copy, not by reference, so this is the number of bytes
108 * that will be copied for each posted item. Each item on the queue must be
109 * the same size.
111 * @return If the queue is successfully create then a handle to the newly
112 * created queue is returned. If the queue cannot be created then 0 is
163 * Creates a new queue instance, and returns a handle by which the new queue
166 * Internally, within the FreeRTOS implementation, queues use two blocks of
167 * memory. The first block is used to hold the queue's data structures. The
168 * second block is used to hold items placed into the queue. If a queue is
170 * dynamically allocated inside the xQueueCreate() function. (see
172 * xQueueCreateStatic() then the application writer must provide the memory that
173 * will get used by the queue. xQueueCreateStatic() therefore allows a queue to
178 * @param uxQueueLength The maximum number of items that the queue can contain.
180 * @param uxItemSize The number of bytes each item in the queue will require.
181 * Items are queued by copy, not by reference, so this is the number of bytes
182 * that will be copied for each posted item. Each item on the queue must be
183 * the same size.
187 * enough to hold the maximum number of items that can be in the queue at any
192 * will be used to hold the queue's data structure.
194 * @return If the queue is created then a handle to the created queue is
208 * // xQueueBuffer will hold the queue structure.
211 * // ucQueueStorage will hold the items posted to the queue. Must be at least
220 * xQueue1 = xQueueCreate( QUEUE_LENGTH, // The number of items the queue can hold.
221 * ITEM_SIZE // The size of each item in the queue
222 …* &( ucQueueStorage[ 0 ] ), // The buffer that will hold the items in the…
223 * &xQueueBuffer ); // The buffer that will hold the queue structure.
225 * // The queue is guaranteed to be created successfully as no dynamic memory
247 * and storage area buffer. These are the same buffers that are supplied
248 * at the time of creation.
250 * @param xQueue The queue for which to retrieve the buffers.
252 * @param ppucQueueStorage Used to return a pointer to the queue's storage
255 * @param ppxStaticQueue Used to return a pointer to the queue's data
277 * Post an item to the front of a queue. The item is queued by copy, not by
282 * @param xQueue The handle to the queue on which the item is to be posted.
284 * @param pvItemToQueue A pointer to the item that is to be placed on the
285 * queue. The size of the items the queue will hold was defined when the
287 * into the queue storage area.
289 * @param xTicksToWait The maximum amount of time the task should block
290 * waiting for space to become available on the queue, should it already
291 * be full. The call will return immediately if this is set to 0 and the
292 * queue is full. The time is defined in tick periods so the constant
295 * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.
327 * // Failed to post the message, even after 10 ticks.
333 * // Send a pointer to a struct AMessage object. Don't block if the
360 * Post an item to the back of a queue. The item is queued by copy, not by
365 * @param xQueue The handle to the queue on which the item is to be posted.
367 * @param pvItemToQueue A pointer to the item that is to be placed on the
368 * queue. The size of the items the queue will hold was defined when the
370 * into the queue storage area.
372 * @param xTicksToWait The maximum amount of time the task should block
373 * waiting for space to become available on the queue, should it already
374 * be full. The call will return immediately if this is set to 0 and the queue
375 * is full. The time is defined in tick periods so the constant
378 * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.
410 * // Failed to post the message, even after 10 ticks.
416 * // Send a pointer to a struct AMessage object. Don't block if the
443 * include the xQueueSendToFront() and xQueueSendToBack() macros. It is
446 * Post an item on a queue. The item is queued by copy, not by reference.
450 * @param xQueue The handle to the queue on which the item is to be posted.
452 * @param pvItemToQueue A pointer to the item that is to be placed on the
453 * queue. The size of the items the queue will hold was defined when the
455 * into the queue storage area.
457 * @param xTicksToWait The maximum amount of time the task should block
458 * waiting for space to become available on the queue, should it already
459 * be full. The call will return immediately if this is set to 0 and the
460 * queue is full. The time is defined in tick periods so the constant
463 * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.
495 * // Failed to post the message, even after 10 ticks.
501 * // Send a pointer to a struct AMessage object. Don't block if the
525 * Only for use with queues that have a length of one - so the queue is either
528 * Post an item on a queue. If the queue is already full then overwrite the
529 * value held in the queue. The item is queued by copy, not by reference.
534 * @param xQueue The handle of the queue to which the data is being sent.
536 * @param pvItemToQueue A pointer to the item that is to be placed on the
537 * queue. The size of the items the queue will hold was defined when the
539 * into the queue storage area.
542 * therefore has the same return values as xQueueSendToFront(). However, pdPASS
543 * is the only value that can be returned because xQueueOverwrite() will write
544 * to the queue even when the queue is already full.
560 * // Write the value 10 to the queue using xQueueOverwrite().
564 * // Peeking the queue should now return 10, but leave the value 10 in
565 * // the queue. A block time of zero is used as it is known that the
572 * // Error unless the item was removed by a different task.
575 * // The queue is still full. Use xQueueOverwrite() to overwrite the
576 * // value held in the queue with 100.
580 * // This time read from the queue, leaving the queue empty once more.
584 * // The value read should be the last value written, even though the
585 * // queue was already full when the value was written.
612 * It is preferred that the macros xQueueSend(), xQueueSendToFront() and
615 * Post an item on a queue. The item is queued by copy, not by reference.
619 * @param xQueue The handle to the queue on which the item is to be posted.
621 * @param pvItemToQueue A pointer to the item that is to be placed on the
622 * queue. The size of the items the queue will hold was defined when the
624 * into the queue storage area.
626 * @param xTicksToWait The maximum amount of time the task should block
627 * waiting for space to become available on the queue, should it already
628 * be full. The call will return immediately if this is set to 0 and the
629 * queue is full. The time is defined in tick periods so the constant
632 * @param xCopyPosition Can take the value queueSEND_TO_BACK to place the
633 * item at the back of the queue, or queueSEND_TO_FRONT to place the item
634 * at the front of the queue (for high priority messages).
636 * @return pdTRUE if the item was successfully posted, otherwise errQUEUE_FULL.
668 * // Failed to post the message, even after 10 ticks.
674 * // Send a pointer to a struct AMessage object. Don't block if the
701 * Receive an item from a queue without removing the item from the queue.
702 * The item is received by copy so a buffer of adequate size must be
703 * provided. The number of bytes copied into the buffer was defined when
704 * the queue was created.
706 * Successfully received items remain on the queue so will be returned again
707 * by the next call, or a call to xQueueReceive().
713 * @param xQueue The handle to the queue from which the item is to be
716 * @param pvBuffer Pointer to the buffer into which the received item will
719 * @param xTicksToWait The maximum amount of time the task should block
720 * waiting for an item to receive should the queue be empty at the time
721 * of the call. The time is defined in tick periods so the constant
723 * xQueuePeek() will return immediately if xTicksToWait is 0 and the queue
726 * @return pdTRUE if an item was successfully received from the queue,
749 * // Failed to create the queue.
754 * // Send a pointer to a struct AMessage object. Don't block if the
762 * // Task to peek the data from the queue.
769 * // Peek a message on the created queue. Block for 10 ticks if a
773 * // pcRxedMessage now points to the struct AMessage variable posted
774 * // by vATask, but the item still remains on the queue.
800 * Receive an item from a queue without removing the item from the queue.
801 * The item is received by copy so a buffer of adequate size must be
802 * provided. The number of bytes copied into the buffer was defined when
803 * the queue was created.
805 * Successfully received items remain on the queue so will be returned again
806 * by the next call, or a call to xQueueReceive().
808 * @param xQueue The handle to the queue from which the item is to be
811 * @param pvBuffer Pointer to the buffer into which the received item will
814 * @return pdTRUE if an item was successfully received from the queue,
833 * Receive an item from a queue. The item is received by copy so a buffer of
834 * adequate size must be provided. The number of bytes copied into the buffer
835 * was defined when the queue was created.
837 * Successfully received items are removed from the queue.
842 * @param xQueue The handle to the queue from which the item is to be
845 * @param pvBuffer Pointer to the buffer into which the received item will
848 * @param xTicksToWait The maximum amount of time the task should block
849 * waiting for an item to receive should the queue be empty at the time
850 * of the call. xQueueReceive() will return immediately if xTicksToWait
851 * is zero and the queue is empty. The time is defined in tick periods so the
855 * @return pdTRUE if an item was successfully received from the queue,
878 * // Failed to create the queue.
883 * // Send a pointer to a struct AMessage object. Don't block if the
891 * // Task to receive from the queue.
898 * // Receive a message on the created queue. Block for 10 ticks if a
902 * // pcRxedMessage now points to the struct AMessage variable posted
923 * Return the number of messages stored in a queue.
925 * @param xQueue A handle to the queue being queried.
927 * @return The number of messages available in the queue.
940 * Return the number of free spaces available in a queue. This is equal to the
941 * number of items that can be sent to the queue before the queue becomes full
944 * @param xQueue A handle to the queue being queried.
946 * @return The number of spaces available in the queue.
959 * Delete a queue - freeing all the memory allocated for storing of items
960 * placed on the queue.
962 * @param xQueue A handle to the queue to be deleted.
981 * Post an item to the front of a queue. It is safe to use this macro from
986 * it would be preferable to store a pointer to the item being queued.
988 * @param xQueue The handle to the queue on which the item is to be posted.
990 * @param pvItemToQueue A pointer to the item that is to be placed on the
991 * queue. The size of the items the queue will hold was defined when the
993 * into the queue storage area.
996 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task
997 * to unblock, and the unblocked task has a priority higher than the currently
999 * a context switch should be requested before the interrupt is exited.
1001 * @return pdTRUE if the data was successfully sent to the queue, otherwise
1004 * Example usage for buffered IO (where the ISR can obtain more than one value
1012 * // We have not woken a task at the start of the ISR.
1015 * // Loop until the buffer is empty.
1018 * // Obtain a byte from the buffer.
1021 * // Post the byte.
1026 * // Now the buffer is empty we can switch context if necessary.
1053 * Post an item to the back of a queue. It is safe to use this macro from
1058 * it would be preferable to store a pointer to the item being queued.
1060 * @param xQueue The handle to the queue on which the item is to be posted.
1062 * @param pvItemToQueue A pointer to the item that is to be placed on the
1063 * queue. The size of the items the queue will hold was defined when the
1065 * into the queue storage area.
1068 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task
1069 * to unblock, and the unblocked task has a priority higher than the currently
1071 * a context switch should be requested before the interrupt is exited.
1073 * @return pdTRUE if the data was successfully sent to the queue, otherwise
1076 * Example usage for buffered IO (where the ISR can obtain more than one value
1084 * // We have not woken a task at the start of the ISR.
1087 * // Loop until the buffer is empty.
1090 * // Obtain a byte from the buffer.
1093 * // Post the byte.
1098 * // Now the buffer is empty we can switch context if necessary.
1125 * Only for use with queues that can hold a single item - so the queue is either
1128 * Post an item on a queue. If the queue is already full then overwrite the
1129 * value held in the queue. The item is queued by copy, not by reference.
1131 * @param xQueue The handle to the queue on which the item is to be posted.
1133 * @param pvItemToQueue A pointer to the item that is to be placed on the
1134 * queue. The size of the items the queue will hold was defined when the
1136 * into the queue storage area.
1139 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task
1140 * to unblock, and the unblocked task has a priority higher than the currently
1142 * a context switch should be requested before the interrupt is exited.
1145 * xQueueGenericSendFromISR(), and therefore has the same return values as
1146 * xQueueSendToFrontFromISR(). However, pdPASS is the only value that can be
1147 * returned because xQueueOverwriteFromISR() will write to the queue even when
1148 * the queue is already full.
1170 * // Write the value 10 to the queue using xQueueOverwriteFromISR().
1174 * // The queue is full, but calling xQueueOverwriteFromISR() again will still
1175 * // pass because the value held in the queue will be overwritten with the
1180 * // Reading from the queue will now return 100.
1186 * // Writing to the queue caused a task to unblock and the unblocked task
1187 * // has a priority higher than or equal to the priority of the currently
1188 * // executing task (the task this interrupt interrupted). Perform a context
1189 * // switch so this interrupt returns directly to the unblocked task.
1190 * // The macro used is port specific and will be either
1191 * // portYIELD_FROM_ISR() or portEND_SWITCHING_ISR() - refer to the documentation
1192 * // page for the port being used.
1215 * include the xQueueSendToBackFromISR() and xQueueSendToFrontFromISR()
1218 * Post an item to the back of a queue. It is safe to use this function from
1223 * it would be preferable to store a pointer to the item being queued.
1225 * @param xQueue The handle to the queue on which the item is to be posted.
1227 * @param pvItemToQueue A pointer to the item that is to be placed on the
1228 * queue. The size of the items the queue will hold was defined when the
1230 * into the queue storage area.
1233 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task
1234 * to unblock, and the unblocked task has a priority higher than the currently
1236 * a context switch should be requested before the interrupt is exited.
1238 * @return pdTRUE if the data was successfully sent to the queue, otherwise
1241 * Example usage for buffered IO (where the ISR can obtain more than one value
1249 * // We have not woken a task at the start of the ISR.
1252 * // Loop until the buffer is empty.
1255 * // Obtain a byte from the buffer.
1258 * // Post the byte.
1263 * // Now the buffer is empty we can switch context if necessary.
1267 * // switch should be requested. The macro used is port specific and
1269 * // refer to the documentation page for the port being used.
1292 * It is preferred that the macros xQueueSendFromISR(),
1302 * it would be preferable to store a pointer to the item being queued.
1304 * @param xQueue The handle to the queue on which the item is to be posted.
1306 * @param pvItemToQueue A pointer to the item that is to be placed on the
1307 * queue. The size of the items the queue will hold was defined when the
1309 * into the queue storage area.
1312 * *pxHigherPriorityTaskWoken to pdTRUE if sending to the queue caused a task
1313 * to unblock, and the unblocked task has a priority higher than the currently
1315 * a context switch should be requested before the interrupt is exited.
1317 * @param xCopyPosition Can take the value queueSEND_TO_BACK to place the
1318 * item at the back of the queue, or queueSEND_TO_FRONT to place the item
1319 * at the front of the queue (for high priority messages).
1321 * @return pdTRUE if the data was successfully sent to the queue, otherwise
1324 * Example usage for buffered IO (where the ISR can obtain more than one value
1332 * // We have not woken a task at the start of the ISR.
1335 * // Loop until the buffer is empty.
1338 * // Obtain a byte from the buffer.
1346 * // Now the buffer is empty we can switch context if necessary.
1350 * // switch should be requested. The macro used is port specific and
1352 * // refer to the documentation page for the port being used.
1381 * @param xQueue The handle to the queue from which the item is to be
1384 * @param pvBuffer Pointer to the buffer into which the received item will
1388 * become available on the queue. If xQueueReceiveFromISR causes such a task
1392 * @return pdTRUE if an item was successfully received from the queue,
1410 * // Failed to create the queue.
1415 * // Post some characters that will be used within an ISR. If the queue
1422 * // ... keep posting characters ... this task may block when the queue
1429 * // ISR that outputs all the characters received on the queue.
1437 * // A character was received. Output the character now.
1440 * // If removing the character from the queue woke the task that was
1441 * // posting onto the queue xTaskWokenByReceive will have been set to
1470 * The functions defined above are for passing data to and from tasks. The
1471 * functions below are the equivalents for passing data to and from
1474 * These functions are called from the co-routine macro implementation and
1475 * should not be called directly from application code. Instead use the macro
1533 * Reset a queue back to its original empty state. The return value is now
1539 * The registry is provided as a means for kernel aware debuggers to
1541 * a queue, semaphore or mutex handle to the registry if you want the handle
1545 * configQUEUE_REGISTRY_SIZE defines the maximum number of handles the
1547 * within FreeRTOSConfig.h for the registry to be available. Its value
1548 * does not affect the number of queues, semaphores and mutexes that can be
1549 * created - just the number that the registry can hold.
1551 * If vQueueAddToRegistry is called more than once with the same xQueue
1552 * parameter, the registry will store the pcQueueName parameter from the
1555 * @param xQueue The handle of the queue being added to the registry. This
1556 * is the handle returned by a call to xQueueCreate(). Semaphore and mutex
1559 * @param pcQueueName The name to be associated with the handle. This is the
1560 * name that the kernel aware debugger will display. The queue registry only
1561 * stores a pointer to the string - so the string must be persistent (global or
1562 * preferably in ROM/Flash), not on the stack.
1570 * The registry is provided as a means for kernel aware debuggers to
1572 * a queue, semaphore or mutex handle to the registry if you want the handle
1574 * remove the queue, semaphore or mutex from the register. If you are not using
1577 * @param xQueue The handle of the queue being removed from the registry.
1584 * The queue registry is provided as a means for kernel aware debuggers to
1586 * up and return the name of a queue in the queue registry from the queue's
1589 * @param xQueue The handle of the queue the name of which will be returned.
1590 * @return If the queue is in the registry then a pointer to the name of the
1591 * queue is returned. If the queue is not in the registry then NULL is
1599 * Generic version of the function used to create a queue using dynamic memory
1601 * RTOS objects that use the queue structure as their base.
1610 * Generic version of the function used to create a queue using dynamic memory
1612 * RTOS objects that use the queue structure as their base.
1623 * Generic version of the function used to retrieve the buffers of statically
1625 * the buffers of other statically created RTOS objects that use the queue
1643 * can be added to the set using calls to xQueueAddToSet().
1644 * xQueueSelectFromSet() is then used to determine which, if any, of the queues
1645 * or semaphores contained in the set is in a state where a queue read or
1648 * Note 1: See the documentation on https://www.FreeRTOS.org/RTOS-queue-sets.html
1652 * Note 2: Blocking on a queue set that contains a mutex will not cause the
1653 * mutex holder to inherit the priority of the blocked task.
1659 * Note 4: A receive (in the case of a queue) or take (in the case of a
1664 * the queues and semaphores contained in the set. uxEventQueueLength specifies
1665 * the maximum number of events that can be queued at once. To be absolutely
1666 * certain that events are not lost uxEventQueueLength should be set to the
1667 * total sum of the length of the queues added to the set, where binary
1679 * @return If the queue set is created successfully then a handle to the created
1693 * Note 1: A receive (in the case of a queue) or take (in the case of a
1697 * @param xQueueOrSemaphore The handle of the queue or semaphore being added to
1698 * the queue set (cast to an QueueSetMemberHandle_t type).
1700 * @param xQueueSet The handle of the queue set to which the queue or semaphore
1703 * @return If the queue or semaphore was successfully added to the queue set
1704 * then pdPASS is returned. If the queue could not be successfully added to the
1715 * be removed from a set if the queue or semaphore is empty.
1720 * @param xQueueOrSemaphore The handle of the queue or semaphore being removed
1721 * from the queue set (cast to an QueueSetMemberHandle_t type).
1723 * @param xQueueSet The handle of the queue set in which the queue or semaphore
1726 * @return If the queue or semaphore was successfully removed from the queue set
1727 * then pdPASS is returned. If the queue was not in the queue set, or the
1736 * xQueueSelectFromSet() selects from the members of a queue set a queue or
1737 * semaphore that either contains data (in the case of a queue) or is available
1738 * to take (in the case of a semaphore). xQueueSelectFromSet() effectively
1739 * allows a task to block (pend) on a read operation on all the queues and
1745 * Note 1: See the documentation on https://www.FreeRTOS.org/RTOS-queue-sets.html
1749 * Note 2: Blocking on a queue set that contains a mutex will not cause the
1750 * mutex holder to inherit the priority of the blocked task.
1752 * Note 3: A receive (in the case of a queue) or take (in the case of a
1756 * @param xQueueSet The queue set on which the task will (potentially) block.
1758 * @param xTicksToWait The maximum time, in ticks, that the calling task will
1759 * remain in the Blocked state (with other tasks executing) to wait for a member
1760 * of the queue set to be ready for a successful queue read or semaphore take
1763 * @return xQueueSelectFromSet() will return the handle of a queue (cast to
1764 * a QueueSetMemberHandle_t type) contained in the queue set that contains data,
1765 * or the handle of a semaphore (cast to a QueueSetMemberHandle_t type) contained
1766 * in the queue set that is available, or NULL if no such queue or semaphore
1767 * exists before before the specified block time expires.