Queues¶
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.
- Returns
N/A
-
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)
- Parameters
queue – Address of the queue.
- Returns
N/A
-
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)
- Parameters
queue – Address of the queue.
data – Address of the data item.
- Returns
N/A
-
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)
- Parameters
queue – Address of the queue.
data – Address of the data item.
- Returns 0
on success
- Returns -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)
- Parameters
queue – Address of the queue.
data – Address of the data item.
- Returns
N/A
-
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)
- Parameters
queue – Address of the queue.
data – Address of the data item.
- Returns 0
on success
- Returns -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)
- Parameters
queue – Address of the queue.
prev – Address of the previous data item.
data – Address of the data item.
- Returns
N/A
-
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)
- Parameters
queue – Address of the queue.
head – Pointer to first node in singly-linked list.
tail – Pointer to last node in singly-linked list.
- Returns 0
on success
- Returns -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)
- Parameters
queue – Address of the queue.
list – Pointer to sys_slist_t object.
- Returns 0
on success
- Returns -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)
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)
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)
- 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)
- 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.
-