nRF5 SDK v17.1.0
Data Structures | Macros | Typedefs | Functions

Module to declare the queue API. More...

Data Structures

struct  sys_queue_item_s
 Queue item descriptor. More...
 

Macros

#define SYS_QUEUE_FOR_EACH(p_queue, p_iterator)
 Macro for iterating through all items in the queue. More...
 

Typedefs

typedef struct sys_queue_item_s sys_queue_item_t
 Queue item descriptor. More...
 
typedef sys_queue_item_t sys_queue_t
 Queue descriptor.
 
typedef bool(* sys_queue_push_predicate_t )(sys_queue_item_t *p_before_item, sys_queue_item_t *p_new_item)
 Prototype of a predicate function for pushing an item into the queue. More...
 

Functions

void sys_queue_init (sys_queue_t *p_queue)
 Function for initializing the queue before any other usage of the queue. More...
 
sys_queue_item_tsys_queue_front (const sys_queue_t *p_queue)
 Function for getting the front (head) item of the queue without removing it. More...
 
sys_queue_item_tsys_queue_back (const sys_queue_t *p_queue)
 Function for getting the back (tail) item of the queue without removing it. More...
 
sys_queue_item_tsys_queue_next (const sys_queue_t *p_queue, const sys_queue_item_t *p_item)
 Function for getting the item, next to the given item of the queue. More...
 
void sys_queue_push_front (sys_queue_t *p_queue, sys_queue_item_t *p_item)
 Function for pushing an item to the front (head) of the queue. More...
 
void sys_queue_push_back (sys_queue_t *p_queue, sys_queue_item_t *p_item)
 Function for pushing an item to the back (tail) of the queue. More...
 
bool sys_queue_push_predicated (sys_queue_t *p_queue, sys_queue_item_t *p_item, sys_queue_push_predicate_t predicate)
 Function for pushing an item to the queue with a predicate. More...
 
void sys_queue_push_predicated_force (sys_queue_t *p_queue, sys_queue_item_t *p_item, sys_queue_push_predicate_t predicate)
 Function for pushing an item to the queue with a predicate forcing insertion to the tail if the predicate fails. More...
 
sys_queue_item_tsys_queue_pop_front (sys_queue_t *p_queue)
 Function for getting and removing the front (head) item from the queue. More...
 
void sys_queue_remove (sys_queue_t *p_queue, sys_queue_item_t *p_item)
 Function for removing an item from the queue. More...
 
void sys_queue_remove_after (sys_queue_t *p_queue, sys_queue_item_t *p_after_item)
 Function for removing the item after the given item from the queue. More...
 
uint8_t sys_queue_size (const sys_queue_t *p_queue)
 Function for returning the current size of a queue, i.e. number of elements inside it. More...
 
sys_queue_item_tsys_queue_at (const sys_queue_t *p_queue, const uint8_t index)
 Function for returning a pointer to the item inside a queue represented by an index. More...
 
void sys_queue_insert (sys_queue_t *p_queue, sys_queue_item_t *p_item, const uint8_t pos)
 Function for inserting an item at the specified position represented by an index in the queue. If this position is too big, it is inserted to the tail of the queue. More...
 
bool sys_queue_is_empty (const sys_queue_t *p_queue)
 Function for determining if a queue is empty. More...
 

Detailed Description

Module to declare the queue API.

The queue module implements a set of routines to deal with queues. Before any calls to its API are issued, a queue must be initialized using sys_queue_init(). The following routines return queue items from different parts of an initialized queue without removing it from the queue: sys_queue_front(), sys_queue_back(), sys_queue_next(), and sys_queue_at(). The following routines insert elements to the queue: sys_queue_push_front(), sys_queue_push_back(), sys_queue_push_predicated(), sys_queue_push_predicated_force(), and sys_queue_insert(). The following routines remove elements from the queue: sys_queue_pop_front(), sys_queue_remove(), sys_queue_remove_after(). These helper routines get information about a queue: sys_queue_size() and sys_queue_is_empty(). The module also supports an iterator macro implemented by SYS_QUEUE_FOR_EACH().

Macro Definition Documentation

#define SYS_QUEUE_FOR_EACH (   p_queue,
  p_iterator 
)
Value:
for (sys_queue_item_t * p_iterator = sys_queue_front(p_queue); \
p_iterator != NULL; \
p_iterator = sys_queue_next(p_queue, p_iterator))

Macro for iterating through all items in the queue.

Parameters
[in]p_queuePointer to the queue (sys_queue_t *).
[in]p_iteratorVariable to be used as an iterator (sys_queue_item_t *).

Typedef Documentation

Queue item descriptor.

In order to store any user data struct in a queue, the user struct should contain a field of type 'sys_queue_item_t'. This field may be at any offset. The user data item can be cast from the queue item, by the GET_PARENT_BY_FIELD() macro from sys_utils.h.

typedef bool(* sys_queue_push_predicate_t)(sys_queue_item_t *p_before_item, sys_queue_item_t *p_new_item)

Prototype of a predicate function for pushing an item into the queue.

As a user of the queue library, implement the predicate function and pass it as a parameter to sys_queue_push_predicated(). You can choose whether insertion of a new item should be done before the given existing item of the queue, or not.

Parameters
[in]p_before_itemPointer to the existing item before which a new item should be inserted.
[in]p_new_itemPointer to the item to be inserted into the queue.
Return values
trueInsertion is to be done before the given item, false otherwise.

Function Documentation

sys_queue_item_t* sys_queue_at ( const sys_queue_t p_queue,
const uint8_t  index 
)

Function for returning a pointer to the item inside a queue represented by an index.

This function searches through the whole queue, so it is relatively slow.

Parameters
[in]p_queueQueue to work with.
[in]indexRequested index.
Return values
Pointerto the requested item or NULL if the queue size is less than index.
sys_queue_item_t* sys_queue_back ( const sys_queue_t p_queue)

Function for getting the back (tail) item of the queue without removing it.

Return a pointer to the item from the tail of the queue but leave it in the queue.

Parameters
[in]p_queueQueue to get the item from.
Return values
Pointerto the tail item of the queue, or NULL if the queue is empty.
sys_queue_item_t* sys_queue_front ( const sys_queue_t p_queue)

Function for getting the front (head) item of the queue without removing it.

Return a pointer to the item from the head of the queue but leave it in the queue.

Parameters
[in]p_queueQueue to get the item from.
Return values
Pointerto the head item of the queue, or NULL if the queue is empty.
void sys_queue_init ( sys_queue_t p_queue)

Function for initializing the queue before any other usage of the queue.

Initialize (reset) the queue to its initial state. The queue becomes empty.

Parameters
[in]p_queueQueue to be initialized.
void sys_queue_insert ( sys_queue_t p_queue,
sys_queue_item_t p_item,
const uint8_t  pos 
)

Function for inserting an item at the specified position represented by an index in the queue. If this position is too big, it is inserted to the tail of the queue.

This function searches through the whole queue, so it is relatively slow.

Parameters
[in]p_queueQueue to insert to.
[in]p_itemItem to be inserted.
[in]posPosition inside the queue (0 is the front).
bool sys_queue_is_empty ( const sys_queue_t p_queue)

Function for determining if a queue is empty.

Parameters
[in]p_queueQueue to be checked.
Return values
Trueif queue is empty, false otherwise.
sys_queue_item_t* sys_queue_next ( const sys_queue_t p_queue,
const sys_queue_item_t p_item 
)

Function for getting the item, next to the given item of the queue.

Return a pointer to the next item after the given one, or NULL if the given item is the last item of the queue.

Parameters
[in]p_queuePointer to the queue.
[in]p_itemPointer to the item.
Return values
Pointerto the next item after the given one, or NULL if the given item is the last item of the queue.
sys_queue_item_t* sys_queue_pop_front ( sys_queue_t p_queue)

Function for getting and removing the front (head) item from the queue.

Get an item from the head of the queue and remove it from the queue.

Parameters
[in]p_queueQueue to get and remove the head item from.
Return values
Pointerto the head item of queue or NULL if the queue is empty.
void sys_queue_push_back ( sys_queue_t p_queue,
sys_queue_item_t p_item 
)

Function for pushing an item to the back (tail) of the queue.

This function inserts an item to the tail of the queue.

Parameters
[in]p_queueQueue to push the item to.
[in]p_itemItem to insert to the tail of the queue.
void sys_queue_push_front ( sys_queue_t p_queue,
sys_queue_item_t p_item 
)

Function for pushing an item to the front (head) of the queue.

This function inserts an item to the head of the queue.

Parameters
[in]p_queueQueue to push the item to.
[in]p_itemItem to insert to the front of the queue.
bool sys_queue_push_predicated ( sys_queue_t p_queue,
sys_queue_item_t p_item,
sys_queue_push_predicate_t  predicate 
)

Function for pushing an item to the queue with a predicate.

Conditionally push an item to the queue using the given predicate that tries to determine the insertion position.

Parameters
[in]p_queueQueue to push the item to.
[in]p_itemItem to be pushed.
[in]predicatePredicate to be used to find the insertion position.
Return values
trueThe item was inserted into the queue, false otherwise.
void sys_queue_push_predicated_force ( sys_queue_t p_queue,
sys_queue_item_t p_item,
sys_queue_push_predicate_t  predicate 
)

Function for pushing an item to the queue with a predicate forcing insertion to the tail if the predicate fails.

Unconditionally push an item to the queue using the given predicate that tries to determine the insertion position. If predicate returns false, then force the insertion to the tail of the queue.

Parameters
[in]p_queueQueue to push item to.
[in]p_itemItem to be pushed.
[in]predicatePredicate to be used to find the insertion position.
void sys_queue_remove ( sys_queue_t p_queue,
sys_queue_item_t p_item 
)

Function for removing an item from the queue.

The given item will be removed from the queue.

Note
The complexity of this function is O(n). Use function sys_queue_remove_after() whenever the previous item of the queue is known.
Parameters
[in]p_queueQueue to remove the item from.
[in]p_itemItem to remove from the queue.
void sys_queue_remove_after ( sys_queue_t p_queue,
sys_queue_item_t p_after_item 
)

Function for removing the item after the given item from the queue.

The item next to the given one will be removed from the queue.

Parameters
[in]p_queueQueue to remove the item from.
[in]p_after_itemNext to this item will be removed.
uint8_t sys_queue_size ( const sys_queue_t p_queue)

Function for returning the current size of a queue, i.e. number of elements inside it.

This function goes through the whole queue, so it is relatively slow.

Parameters
[in]p_queueQueue to work with.
Return values
Numberof items currently inserted into the queue.

Documentation feedback | Developer Zone | Subscribe | Updated