Zephyr API Documentation 4.5.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
Queue APIs

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.

Detailed Description

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.

Macro Definition Documentation

◆ K_QUEUE_DEFINE

#define K_QUEUE_DEFINE ( name)

#include <zephyr/kernel.h>

Value:
Z_QUEUE_INITIALIZER(name)
#define STRUCT_SECTION_ITERABLE(struct_type, varname)
Defines a new element for an iterable section.
Definition iterable_sections.h:244
Kernel queue structure.
Definition kernel.h:2340

Statically define and initialize a queue.

The queue can be accessed outside the module where it is defined using:

extern struct k_queue <name>;
Parameters
nameName of the queue.

Function Documentation

◆ k_queue_alloc_append()

int32_t k_queue_alloc_append ( struct k_queue * queue,
void * data )
isr-ok

#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.

Note
The link is allocated with the queue lock held, so the allocator's lock nests inside the queue lock and the cost of the allocation is part of the critical section.
Parameters
queueAddress of the queue.
dataAddress of the data item.
Return values
0on success
-ENOMEMThe resource pool of the calling thread has insufficient RAM

◆ k_queue_alloc_prepend()

int32_t k_queue_alloc_prepend ( struct k_queue * queue,
void * data )
isr-ok

#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.

Note
The link is allocated with the queue lock held, so the allocator's lock nests inside the queue lock and the cost of the allocation is part of the critical section.
Parameters
queueAddress of the queue.
dataAddress of the data item.
Return values
0on success
-ENOMEMThe resource pool of the calling thread has insufficient RAM

◆ k_queue_append()

void k_queue_append ( struct k_queue * queue,
void * data )
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.

Parameters
queueAddress of the queue.
dataAddress of the data item.

◆ k_queue_append_list()

int k_queue_append_list ( struct k_queue * queue,
void * head,
void * tail )
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.

Parameters
queueAddress of the queue.
headPointer to first node in singly-linked list.
tailPointer to last node in singly-linked list.
Return values
0on success
-EINVALhead or tail is a null pointer

◆ k_queue_cancel_wait()

void k_queue_cancel_wait ( struct k_queue * queue)
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.

Note
Does nothing when no thread or k_work_poll item is waiting on queue.
Parameters
queueAddress of the queue.

◆ k_queue_get()

void * k_queue_get ( struct k_queue * queue,
k_timeout_t timeout )
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.

Note
timeout must be set to K_NO_WAIT if called from ISR.
A timeout and a k_queue_cancel_wait() are both reported as a null return; the two cannot be told apart from the return value alone.
Parameters
queueAddress of the queue.
timeoutWaiting period to obtain a data item, or one of the special values K_NO_WAIT and K_FOREVER.
Return values
non-NULLAddress of the data item that was removed.
NULLThe queue was empty and timeout was K_NO_WAIT, the waiting period expired, or the wait was cancelled by k_queue_cancel_wait().

◆ k_queue_init()

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.

Note
queue must be initialized before any other queue API is called on it, and must not be initialized again while it is in use.
Parameters
queueAddress of the queue.

◆ k_queue_insert()

void k_queue_insert ( struct k_queue * queue,
void * prev,
void * data )
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.

Parameters
queueAddress of the queue.
prevAddress 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.
dataAddress of the data item.

◆ k_queue_is_empty()

int k_queue_is_empty ( struct k_queue * queue)
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.

Parameters
queueAddress of the queue.
Return values
1queue is empty.
0queue holds at least one item.

◆ k_queue_merge_slist()

int k_queue_merge_slist ( struct k_queue * queue,
sys_slist_t * list )
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.

Parameters
queueAddress of the queue.
listPointer to sys_slist_t object.
Return values
0on success
-EINVALlist is empty

◆ k_queue_peek_head()

void * k_queue_peek_head ( struct k_queue * queue)
isr-ok

#include <zephyr/kernel.h>

Peek element at the head of queue.

Return element from the head of queue without removing it.

Parameters
queueAddress of the queue.
Return values
non-NULLAddress of the head element.
NULLqueue is empty.

◆ k_queue_peek_tail()

void * k_queue_peek_tail ( struct k_queue * queue)
isr-ok

#include <zephyr/kernel.h>

Peek element at the tail of queue.

Return element from the tail of queue without removing it.

Parameters
queueAddress of the queue.
Return values
non-NULLAddress of the tail element.
NULLqueue is empty.

◆ k_queue_prepend()

void k_queue_prepend ( struct k_queue * queue,
void * data )
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.

Parameters
queueAddress of the queue.
dataAddress of the data item.

◆ k_queue_remove()

bool k_queue_remove ( struct k_queue * queue,
void * data )
isr-ok

#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.

Note
Removing an item does not wake a thread waiting in k_queue_get().
Parameters
queueAddress of the queue.
dataAddress of the data item.
Return values
truedata was found and removed.
falsedata was not queued.

◆ k_queue_unique_append()

bool k_queue_unique_append ( struct k_queue * queue,
void * data )
isr-ok

#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.

Note
Returns true when a waiting thread takes data at once, in which case nothing is left in the queue.
Parameters
queueAddress of the queue.
dataAddress of the data item.
Return values
truedata was added, or handed directly to a waiting thread.
falseAn item carrying the same data pointer was already queued.