Zephyr API Documentation  3.7.0-rc1
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
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:
Z_QUEUE_INITIALIZER(name)
#define STRUCT_SECTION_ITERABLE(struct_type, varname)
Defines a new element for an iterable section.
Definition: iterable_sections.h:216
Definition: kernel.h:1850

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 
)

#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
queueAddress of the queue.
dataAddress of the data item.
Return values
0on success
-ENOMEMif 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
queueAddress of the queue.
dataAddress of the data item.
Return values
0on success
-ENOMEMif 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
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 
)

#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
queueAddress of the queue.
headPointer to first node in singly-linked list.
tailPointer to last node in singly-linked list.
Return values
0on success
-EINVALon 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
queueAddress 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
queueAddress of the queue.
timeoutWaiting 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
queueAddress 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
queueAddress of the queue.
prevAddress of the previous data item.
dataAddress 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
queueAddress 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
queueAddress of the queue.
listPointer to sys_slist_t object.
Return values
0on success
-EINVALon 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
queueAddress 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
queueAddress 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
queueAddress of the queue.
dataAddress 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
queueAddress of the queue.
dataAddress 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
queueAddress of the queue.
dataAddress of the data item.
Returns
true if data item was added, false if not