Queue APIs

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

Macro Definition Documentation

K_QUEUE_DEFINE

#define K_QUEUE_DEFINE

(

name

)

#include <zephyr/kernel.h>

Value:

        STRUCT_SECTION_ITERABLE(k_queue, name) = \
                Z_QUEUE_INITIALIZER(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.

Function Documentation

k_queue_alloc_append()

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

#include <zephyr/kernel.h>

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

k_queue_alloc_prepend()

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

#include <zephyr/kernel.h>

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

k_queue_append()

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

#include <zephyr/kernel.h>

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.

k_queue_append_list()

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

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

k_queue_cancel_wait()

void k_queue_cancel_wait

(

struct k_queue *

queue

)

#include <zephyr/kernel.h>

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.

k_queue_get()

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

#include <zephyr/kernel.h>

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

timeout must be set to K_NO_WAIT if called from ISR.

Function properties (list may not be complete)

isr-ok

Parameters

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.

Returns

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

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.

Parameters

queue

Address of the queue.

k_queue_insert()

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

#include <zephyr/kernel.h>

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.

k_queue_is_empty()

int k_queue_is_empty

(

struct k_queue *

queue

)

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

Function properties (list may not be complete)

isr-ok

Parameters

queue

Address of the queue.

Returns

Non-zero if the queue is empty.

0 if data is available.

k_queue_merge_slist()

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

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

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

k_queue_peek_head()

void * k_queue_peek_head

(

struct k_queue *

queue

)

#include <zephyr/kernel.h>

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.

k_queue_peek_tail()

void * k_queue_peek_tail

(

struct k_queue *

queue

)

#include <zephyr/kernel.h>

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.

k_queue_prepend()

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

#include <zephyr/kernel.h>

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.

k_queue_remove()

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

#include <zephyr/kernel.h>

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

timeout must be set to K_NO_WAIT if called from ISR.

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 removed

k_queue_unique_append()

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

#include <zephyr/kernel.h>

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