|
Zephyr API Documentation 4.5.99
A Scalable Open Source RTOS
|
A queue is a kernel object, so a user thread reaches one only after the object has been granted to that thread with k_object_access_grant(). More...
Macros | |
| #define | K_QUEUE_DEFINE(name) |
| Statically define and initialize a queue. | |
Functions | |
| void | k_queue_init (struct k_queue *queue) |
| Initialize a queue. | |
| void | k_queue_cancel_wait (struct k_queue *queue) |
| Cancel waiting on a queue. | |
| void | k_queue_append (struct k_queue *queue, void *data) |
| Append an element to the end of a queue. | |
| int32_t | k_queue_alloc_append (struct k_queue *queue, void *data) |
| Append an element to the end of a queue, allocating the link. | |
| void | k_queue_prepend (struct k_queue *queue, void *data) |
| Prepend an element to a queue. | |
| int32_t | k_queue_alloc_prepend (struct k_queue *queue, void *data) |
| Prepend an element to a queue, allocating the link. | |
| void | k_queue_insert (struct k_queue *queue, void *prev, void *data) |
| Insert an element into a queue. | |
| int | k_queue_append_list (struct k_queue *queue, void *head, void *tail) |
| Atomically append a list of elements to a queue. | |
| int | k_queue_merge_slist (struct k_queue *queue, sys_slist_t *list) |
| Atomically add a list of elements to a queue. | |
| void * | k_queue_get (struct k_queue *queue, k_timeout_t timeout) |
| Get an element from a queue. | |
| bool | k_queue_remove (struct k_queue *queue, void *data) |
| Remove an element from a queue. | |
| bool | k_queue_unique_append (struct k_queue *queue, void *data) |
| Append an element to a queue only if it's not present already. | |
| int | k_queue_is_empty (struct k_queue *queue) |
| Query a queue to see if it has data available. | |
| void * | k_queue_peek_head (struct k_queue *queue) |
| Peek element at the head of queue. | |
| void * | k_queue_peek_tail (struct k_queue *queue) |
| Peek element at the tail of queue. | |
A queue is a kernel object, so a user thread reaches one only after the object has been granted to that thread with k_object_access_grant().
Only the entry points declared as system calls may be called from a user thread: k_queue_init(), k_queue_cancel_wait(), k_queue_alloc_append(), k_queue_alloc_prepend(), k_queue_get(), k_queue_is_empty(), k_queue_peek_head() and k_queue_peek_tail(). k_queue_append() and the other list, removal and duplicate-check entry points execute in supervisor mode only and are not available across the boundary.
The data pointer crosses the system call boundary unchecked in both directions. The allocating variants store it in a kernel-allocated link node without dereferencing it, and k_queue_get() and the peek variants hand back the stored pointer unchanged. Nothing checks that the receiving thread can reach the memory the item lives in, so an item queued by one user thread can be retrieved by another that cannot use it; keeping the two consistent is the application's responsibility, not the queue's.
| #define K_QUEUE_DEFINE | ( | name | ) |
#include <zephyr/kernel.h>
Statically define and initialize a queue.
The queue can be accessed outside the module where it is defined using:
| name | Name of the queue. |
#include <zephyr/kernel.h>
Append an element to the end of a queue, allocating the link.
This routine appends data to the end of queue, like k_queue_append(), except that the queue link is taken from a pool instead of from data itself. The link is released automatically once the item has been retrieved or removed, and the first pointer-sized field of data stays available to the caller. The data is not copied.
The link is allocated from the resource pool of the calling thread, or from the system heap when called from ISR context. A thread inherits the resource pool of the thread that creates it, and the main thread starts on the system heap when CONFIG_HEAP_MEM_POOL_SIZE is set, so threads have a pool by default; see k_thread_heap_assign() and k_thread_system_pool_assign(). Only a thread left without a pool fails here, with -ENOMEM, and it does so whether or not CONFIG_HEAP_MEM_POOL_SIZE is set.
If a thread is already waiting in k_queue_get() on queue, data is handed to that thread directly, no link is allocated, and this routine cannot fail.
| queue | Address of the queue. |
| data | Address of the data item. |
| 0 | on success |
| -ENOMEM | The resource pool of the calling thread has insufficient RAM |
#include <zephyr/kernel.h>
Prepend an element to a queue, allocating the link.
This routine prepends data to queue, like k_queue_prepend(), except that the queue link is taken from a pool instead of from data itself. The link is released automatically once the item has been retrieved or removed, and the first pointer-sized field of data stays available to the caller. The data is not copied.
The link is allocated from the resource pool of the calling thread, or from the system heap when called from ISR context. A thread inherits the resource pool of the thread that creates it, and the main thread starts on the system heap when CONFIG_HEAP_MEM_POOL_SIZE is set, so threads have a pool by default; see k_thread_heap_assign() and k_thread_system_pool_assign(). Only a thread left without a pool fails here, with -ENOMEM, and it does so whether or not CONFIG_HEAP_MEM_POOL_SIZE is set.
If a thread is already waiting in k_queue_get() on queue, data is handed to that thread directly, no link is allocated, and this routine cannot fail.
| queue | Address of the queue. |
| data | Address of the data item. |
| 0 | on success |
| -ENOMEM | The resource pool of the calling thread has insufficient RAM |
|
isr-ok |
#include <zephyr/kernel.h>
Append an element to the end of a queue.
This routine appends data to the end of queue.
The item is not copied. The queue keeps its link in the first pointer-sized field of data, which is why that field is reserved for the kernel and why data must be aligned as required for a pointer. The item must stay valid until it has been retrieved with k_queue_get() or removed with k_queue_remove(), and the reserved field must not be written to while the item is queued. The rest of the item stays available to the caller and may be updated in place.
If a thread is already waiting in k_queue_get() on queue, data is handed to that thread directly and never enters the queue. The thread is made ready and consumes data as soon as it runs.
| queue | Address of the queue. |
| data | Address of the data item. |
|
isr-ok |
#include <zephyr/kernel.h>
Atomically append a list of elements to a queue.
This routine adds a list of data items to queue in one operation. The data items must be in a singly-linked list, with the first pointer-sized field in each data item pointing to the next data item; the list must be NULL-terminated.
Waiting threads are served first, one item each, until either the list is exhausted or no thread is left waiting. Only what remains is appended to the queue, and the whole operation is done under a single acquisition of the queue lock.
| queue | Address of the queue. |
| head | Pointer to first node in singly-linked list. |
| tail | Pointer to last node in singly-linked list. |
| 0 | on success |
| -EINVAL | head or tail is a null pointer |
|
isr-ok |
#include <zephyr/kernel.h>
Cancel waiting on a queue.
This routine causes the first thread pending on queue, if any, to return from k_queue_get() with a null value, as if its timeout had expired.
Every k_poll() call waiting on queue is woken with -EINTR and the K_POLL_STATE_CANCELLED state, and every k_work_poll item waiting on it is submitted. As described above a subsequent call to k_queue_get() returns a null value.
| queue | Address of the queue. |
|
isr-ok |
#include <zephyr/kernel.h>
Get an element from a queue.
This routine removes and returns the first data item of queue.
When the item was queued by k_queue_alloc_append() or k_queue_alloc_prepend(), the link allocated on its behalf is released here and the caller receives the original data pointer. The queue lock is released before the call returns.
| queue | Address of the queue. |
| timeout | Waiting period to obtain a data item, or one of the special values K_NO_WAIT and K_FOREVER. |
| non-NULL | Address of the data item that was removed. |
| NULL | The queue was empty and timeout was K_NO_WAIT, the waiting period expired, or the wait was cancelled by k_queue_cancel_wait(). |
| void k_queue_init | ( | struct k_queue * | queue | ) |
#include <zephyr/kernel.h>
Initialize a queue.
This routine initializes a queue object, prior to its first use. The queue is left empty, with no thread waiting on it.
| queue | Address of the queue. |
|
isr-ok |
#include <zephyr/kernel.h>
Insert an element into a queue.
This routine inserts data into queue directly after prev. When prev is a null pointer, data is inserted at the head of the queue.
prev must itself be queued without an allocated link, that is through k_queue_append(), k_queue_prepend() or k_queue_insert(). The queue stores its links in the items themselves, whereas an item queued by k_queue_alloc_append() or k_queue_alloc_prepend() is represented by a link allocated on its behalf; passing such a data pointer here makes the queue treat the item as that link and corrupts the list.
The item is not copied. The queue keeps its link in the first pointer-sized field of data, which is why that field is reserved for the kernel and why data must be aligned as required for a pointer. The item must stay valid until it has been retrieved with k_queue_get() or removed with k_queue_remove(), and the reserved field must not be written to while the item is queued. The rest of the item stays available to the caller and may be updated in place.
If a thread is already waiting in k_queue_get() on queue, data is handed to that thread directly and never enters the queue; prev plays no part in that case.
| queue | Address of the queue. |
| prev | Address of the item to insert data after, or a null pointer to insert at the head of the queue. The item must have been queued without an allocated link. |
| data | Address of the data item. |
|
isr-ok |
#include <zephyr/kernel.h>
Query a queue to see if it has data available.
Note that the data might be already gone by the time this function returns if other threads are also trying to read from the queue.
| queue | Address of the queue. |
| 1 | queue is empty. |
| 0 | queue holds at least one item. |
|
isr-ok |
#include <zephyr/kernel.h>
Atomically add a list of elements to a queue.
This routine adds a list of data items to queue in one operation. The data items must be in a singly-linked list implemented using a sys_slist_t object. Upon completion, the original list is empty. The caller is responsible for ensuring that list is not concurrently accessed by other threads or ISRs.
As with k_queue_append_list(), waiting threads are served first, one item each, and only the remainder reaches the queue.
| queue | Address of the queue. |
| list | Pointer to sys_slist_t object. |
| 0 | on success |
| -EINVAL | list is empty |
|
isr-ok |
#include <zephyr/kernel.h>
Peek element at the head of queue.
Return element from the head of queue without removing it.
| queue | Address of the queue. |
| non-NULL | Address of the head element. |
| NULL | queue is empty. |
|
isr-ok |
#include <zephyr/kernel.h>
Peek element at the tail of queue.
Return element from the tail of queue without removing it.
| queue | Address of the queue. |
| non-NULL | Address of the tail element. |
| NULL | queue is empty. |
|
isr-ok |
#include <zephyr/kernel.h>
Prepend an element to a queue.
This routine prepends data to queue.
The item is not copied. The queue keeps its link in the first pointer-sized field of data, which is why that field is reserved for the kernel and why data must be aligned as required for a pointer. The item must stay valid until it has been retrieved with k_queue_get() or removed with k_queue_remove(), and the reserved field must not be written to while the item is queued. The rest of the item stays available to the caller and may be updated in place.
If a thread is already waiting in k_queue_get() on queue, data is handed to that thread directly and never enters the queue. The thread is made ready and consumes data as soon as it runs.
| queue | Address of the queue. |
| data | Address of the data item. |
#include <zephyr/kernel.h>
Remove an element from a queue.
This routine removes data from queue, wherever it sits in the queue, and releases the link allocated for it if it was queued by k_queue_alloc_append() or k_queue_alloc_prepend().
Queued items are compared by their data pointer, so items queued through the allocating variants are found as well. The queue is walked once, so the cost grows with the number of queued items.
| queue | Address of the queue. |
| data | Address of the data item. |
#include <zephyr/kernel.h>
Append an element to a queue only if it's not present already.
This routine appends data to queue unless an item carrying the same data pointer is already queued. The membership test walks the queue, so the cost grows with the number of queued items.
The item is not copied, and its first pointer-sized field is used by the queue as it is with k_queue_append().
Items are compared by their data pointer, so items queued through k_queue_alloc_append() or k_queue_alloc_prepend() are reported as present as well, even though the queue holds a link allocated on their behalf rather than the item itself.
| queue | Address of the queue. |
| data | Address of the data item. |