Queues

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.

Return

N/A

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

Note

Can be called by ISRs.

Return

N/A

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.

Note

Can be called by ISRs.

Return

N/A

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.

Note

Can be called by ISRs.

Parameters

  • queue: Address of the queue.

  • data: Address of the data item.

Return Value

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

Note

Can be called by ISRs.

Return

N/A

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.

Note

Can be called by ISRs.

Parameters

  • queue: Address of the queue.

  • data: Address of the data item.

Return Value

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

Note

Can be called by ISRs.

Return

N/A

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.

Note

Can be called by ISRs.

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 Value

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

Note

Can be called by ISRs.

Parameters

  • queue: Address of the queue.

  • list: Pointer to sys_slist_t object.

Return Value

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

Note

Can be called by ISRs, but timeout must be set to K_NO_WAIT.

Return

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

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.

static inline 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.

Note

Can be called by ISRs

Return

true if data item was removed

Parameters

  • queue: Address of the queue.

  • data: Address of the data item.

static inline 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.

Note

Can be called by ISRs

Return

true if data item was added, false if not

Parameters

  • queue: Address of the queue.

  • data: Address of the data item.

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.

Note

Can be called by ISRs.

Return

Non-zero if the queue is empty.

Return

0 if data is available.

Parameters

  • queue: Address of the queue.

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.

Return

Head element, or NULL if queue is empty.

Parameters

  • queue: Address of the queue.

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.

Return

Tail element, or NULL if queue is empty.

Parameters

  • queue: Address of the queue.