Queues

A Queue in Zephyr is a kernel object that implements a traditional queue, allowing threads and ISRs to add and remove data items of any size. The queue is similar to a FIFO and serves as the underlying implementation for both k_fifo and k_lifo. For more information on usage see k_fifo.

Configuration Options

Related configuration options:

  • None

API Reference

group queue_apis

Defines

K_QUEUE_DEFINE(name)

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:

  • name – Name of the queue.

Functions

void k_queue_init(struct k_queue *queue)

Initialize a queue.

This routine initializes a queue object, prior to its first use.

Parameters:

  • queue – Address of the queue.

void k_queue_cancel_wait(struct k_queue *queue)

Cancel waiting on a queue.

This routine causes first thread pending on queue, if any, to return from k_queue_get() call with NULL value (as if timeout expired). If the queue is being waited on by k_poll(), it will return with -EINTR and K_POLL_STATE_CANCELLED state (and per above, subsequent k_queue_get() will return NULL).

Function properties (list may not be complete)

isr-ok

Parameters:

  • queue – Address of the queue.

void k_queue_append(struct k_queue *queue, void *data)

Append an element to the end of a queue.

This routine appends a data item to queue. A queue data item must be aligned on a word boundary, and the first word of the item is reserved for the kernel’s use.

Function properties (list may not be complete)

isr-ok

Parameters:

  • queue – Address of the queue.

  • data – Address of the data item.

int32_t k_queue_alloc_append(struct k_queue *queue, void *data)

Append an element to a queue.

This routine appends a data item to queue. There is an implicit memory allocation to create an additional temporary bookkeeping data structure from the calling thread’s resource pool, which is automatically freed when the item is removed. The data itself is not copied.

Function properties (list may not be complete)

isr-ok

Parameters:

  • queue – Address of the queue.

  • data – Address of the data item.

Return values:

  • 0 – on success

  • -ENOMEM – if there isn’t sufficient RAM in the caller’s resource pool

void k_queue_prepend(struct k_queue *queue, void *data)

Prepend an element to a queue.

This routine prepends a data item to queue. A queue data item must be aligned on a word boundary, and the first word of the item is reserved for the kernel’s use.

Function properties (list may not be complete)

isr-ok

Parameters:

  • queue – Address of the queue.

  • data – Address of the data item.

int32_t k_queue_alloc_prepend(struct k_queue *queue, void *data)

Prepend an element to a queue.

This routine prepends a data item to queue. There is an implicit memory allocation to create an additional temporary bookkeeping data structure from the calling thread’s resource pool, which is automatically freed when the item is removed. The data itself is not copied.

Function properties (list may not be complete)

isr-ok

Parameters:

  • queue – Address of the queue.

  • data – Address of the data item.

Return values:

  • 0 – on success

  • -ENOMEM – if there isn’t sufficient RAM in the caller’s resource pool

void k_queue_insert(struct k_queue *queue, void *prev, void *data)

Inserts an element to a queue.

This routine inserts a data item to queue after previous item. A queue data item must be aligned on a word boundary, and the first word of the item is reserved for the kernel’s use.

Function properties (list may not be complete)

isr-ok

Parameters:

  • queue – Address of the queue.

  • prev – Address of the previous data item.

  • data – Address of the data item.

int k_queue_append_list(struct k_queue *queue, void *head, void *tail)

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 word in each data item pointing to the next data item; the list must be NULL-terminated.

Function properties (list may not be complete)

isr-ok

Parameters:

  • queue – Address of the queue.

  • head – Pointer to first node in singly-linked list.

  • tail – Pointer to last node in singly-linked list.

Return values:

  • 0 – on success

  • -EINVAL – on invalid supplied data

int k_queue_merge_slist(struct k_queue *queue, sys_slist_t *list)

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.

Function properties (list may not be complete)

isr-ok

Parameters:

  • queue – Address of the queue.

  • list – Pointer to sys_slist_t object.

Return values:

  • 0 – on success

  • -EINVAL – on invalid data

void *k_queue_get(struct k_queue *queue, k_timeout_t timeout)

Get an element from a queue.

This routine removes first data item from queue. The first word of the data item is reserved for the kernel’s use.

Function properties (list may not be complete)

isr-ok

Note

timeout must be set to K_NO_WAIT if called from ISR.

Parameters:

  • queue – Address of the queue.

  • timeout – Non-negative waiting period to obtain a data item or one of the special values K_NO_WAIT and K_FOREVER.

Returns:

Address of the data item if successful; NULL if returned without waiting, or waiting period timed out.

bool k_queue_remove(struct k_queue *queue, void *data)

Remove an element from a queue.

This routine removes data item from queue. The first word of the data item is reserved for the kernel’s use. Removing elements from k_queue rely on sys_slist_find_and_remove which is not a constant time operation.

Function properties (list may not be complete)

isr-ok

Note

timeout must be set to K_NO_WAIT if called from ISR.

Parameters:

  • queue – Address of the queue.

  • data – Address of the data item.

Returns:

true if data item was removed

bool k_queue_unique_append(struct k_queue *queue, void *data)

Append an element to a queue only if it’s not present already.

This routine appends data item to queue. The first word of the data item is reserved for the kernel’s use. Appending elements to k_queue relies on sys_slist_is_node_in_list which is not a constant time operation.

Function properties (list may not be complete)

isr-ok

Parameters:

  • queue – Address of the queue.

  • data – Address of the data item.

Returns:

true if data item was added, false if not

int k_queue_is_empty(struct k_queue *queue)

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.

Function properties (list may not be complete)

isr-ok

Parameters:

  • queue – Address of the queue.

Returns:

Non-zero if the queue is empty.

Returns:

0 if data is available.

void *k_queue_peek_head(struct k_queue *queue)

Peek element at the head of queue.

Return element from the head of queue without removing it.

Parameters:

  • queue – Address of the queue.

Returns:

Head element, or NULL if queue is empty.

void *k_queue_peek_tail(struct k_queue *queue)

Peek element at the tail of queue.

Return element from the tail of queue without removing it.

Parameters:

  • queue – Address of the queue.

Returns:

Tail element, or NULL if queue is empty.