Zephyr API Documentation 4.5.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
LIFO APIs

A LIFO is a typed view of a queue, so the same rule applies as for the FIFO: a user thread needs the underlying k_queue granted to it. More...

Macros

#define k_lifo_init(lifo)
 Initialize a LIFO queue.
#define k_lifo_put(lifo, data)
 Add an element to a LIFO queue.
#define k_lifo_alloc_put(lifo, data)
 Add an element to a LIFO queue.
#define k_lifo_get(lifo, timeout)
 Get an element from a LIFO queue.
#define K_LIFO_DEFINE(name)
 Statically define and initialize a LIFO queue.

Detailed Description

A LIFO is a typed view of a queue, so the same rule applies as for the FIFO: a user thread needs the underlying k_queue granted to it.

k_lifo_init(), k_lifo_alloc_put() and k_lifo_get() expand to system calls and are callable from a user thread, while k_lifo_put() expands to k_queue_prepend(), which is supervisor mode only.

Macro Definition Documentation

◆ k_lifo_alloc_put

#define k_lifo_alloc_put ( lifo,
data )
isr-ok

#include <zephyr/kernel.h>

Value:
({ \
void *_data = data; \
SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_lifo, alloc_put, lifo, _data); \
int lap_ret = k_queue_alloc_prepend(&(lifo)->_queue, _data); \
SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_lifo, alloc_put, lifo, _data, lap_ret); \
lap_ret; \
})
int32_t k_queue_alloc_prepend(struct k_queue *queue, void *data)
Prepend an element to a queue, allocating the link.
Kernel LIFO structure.
Definition kernel.h:3430

Add an element to a LIFO queue.

This routine adds data to the head of lifo, like k_lifo_put(), except that the queue link is taken from a pool instead of from data itself. The link is released automatically once the item has been retrieved, and the first pointer-sized field of data stays available to the caller. The data is not copied.

The link is allocated from the resource pool of the calling thread, or from the system heap when called from ISR context. A thread inherits the resource pool of the thread that creates it, and the main thread starts on the system heap when CONFIG_HEAP_MEM_POOL_SIZE is set, so threads have a pool by default; see k_thread_heap_assign() and k_thread_system_pool_assign(). Only a thread left without a pool fails here, with -ENOMEM, and it does so whether or not CONFIG_HEAP_MEM_POOL_SIZE is set.

If a thread is already waiting in k_lifo_get() on lifo, data is handed to that thread directly, no link is allocated, and this routine cannot fail.

Note
The link is allocated with the queue lock held, so the allocator's lock nests inside the queue lock and the cost of the allocation is part of the critical section.
Parameters
lifoAddress of the LIFO.
dataAddress of the data item.
Return values
0on success
-ENOMEMThe resource pool of the calling thread has insufficient RAM

◆ K_LIFO_DEFINE

#define K_LIFO_DEFINE ( name)

#include <zephyr/kernel.h>

Value:
Z_LIFO_INITIALIZER(name)
#define STRUCT_SECTION_ITERABLE(struct_type, varname)
Defines a new element for an iterable section.
Definition iterable_sections.h:244

Statically define and initialize a LIFO queue.

The LIFO queue can be accessed outside the module where it is defined using:

extern struct k_lifo <name>;
Parameters
nameName of the fifo.

◆ k_lifo_get

#define k_lifo_get ( lifo,
timeout )
isr-ok

#include <zephyr/kernel.h>

Value:
({ \
SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_lifo, get, lifo, timeout); \
void *lg_ret = k_queue_get(&(lifo)->_queue, timeout); \
SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_lifo, get, lifo, timeout, lg_ret); \
lg_ret; \
})
void * k_queue_get(struct k_queue *queue, k_timeout_t timeout)
Get an element from a queue.

Get an element from a LIFO queue.

This routine removes and returns the most recently added data item of lifo.

When the item was added by k_lifo_alloc_put(), the link allocated on its behalf is released here and the caller receives the original data pointer. The queue lock is released before the call returns.

Note
timeout must be set to K_NO_WAIT if called from ISR.
A timeout is reported as a null return. No cancel operation exists for a LIFO, so a null return from a waiting call is a timeout and nothing else.
Parameters
lifoAddress of the LIFO queue.
timeoutWaiting period to obtain a data item, or one of the special values K_NO_WAIT and K_FOREVER.
Return values
non-NULLAddress of the data item that was removed.
NULLThe LIFO was empty and timeout was K_NO_WAIT, or the waiting period expired.

◆ k_lifo_init

#define k_lifo_init ( lifo)

#include <zephyr/kernel.h>

Value:
({ \
SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_lifo, init, lifo); \
k_queue_init(&(lifo)->_queue); \
K_OBJ_CORE_INIT(K_OBJ_CORE(lifo), _obj_type_lifo); \
K_OBJ_CORE_LINK(K_OBJ_CORE(lifo)); \
SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_lifo, init, lifo); \
})
#define K_OBJ_CORE(kobj)
Convert kernel object pointer into its object core pointer.
Definition obj_core.h:25

Initialize a LIFO queue.

This routine initializes a LIFO queue object, prior to its first use. The LIFO is left empty, with no thread waiting on it.

Note
lifo must be initialized before any other LIFO API is called on it, and must not be initialized again while it is in use.
Parameters
lifoAddress of the LIFO queue.

◆ k_lifo_put

#define k_lifo_put ( lifo,
data )
isr-ok

#include <zephyr/kernel.h>

Value:
({ \
void *_data = data; \
SYS_PORT_TRACING_OBJ_FUNC_ENTER(k_lifo, put, lifo, _data); \
k_queue_prepend(&(lifo)->_queue, _data); \
SYS_PORT_TRACING_OBJ_FUNC_EXIT(k_lifo, put, lifo, _data); \
})

Add an element to a LIFO queue.

This routine adds data to the head of lifo, so that it is the next item k_lifo_get() returns.

The item is not copied. The LIFO keeps its link in the first pointer-sized field of data, which is why that field is reserved for the kernel and why data must be aligned as required for a pointer. The item must stay valid until it has been retrieved with k_lifo_get(), and the reserved field must not be written to while it is queued. The rest of the item stays available to the caller and may be updated in place.

If a thread is already waiting in k_lifo_get() on lifo, data is handed to that thread directly and never enters the LIFO.

Parameters
lifoAddress of the LIFO queue.
dataAddress of the data item.