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_t *	sys_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_t *	sys_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_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. 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_t *	sys_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_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. 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_queue	Pointer to the queue (sys_queue_t *).
[in]	p_iterator	Variable to be used as an iterator (sys_queue_item_t *).

Typedef Documentation

typedef struct sys_queue_item_s sys_queue_item_t

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_item	Pointer to the existing item before which a new item should be inserted.
[in]	p_new_item	Pointer to the item to be inserted into the queue.

Return values

true	Insertion 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_queue	Queue to work with.
[in]	index	Requested index.

Return values

Pointer

to 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_queue

Queue to get the item from.

Return values

Pointer

to 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_queue

Queue to get the item from.

Return values

Pointer

to 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_queue

Queue 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_queue	Queue to insert to.
[in]	p_item	Item to be inserted.
[in]	pos	Position 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_queue

Queue to be checked.

Return values

True	if 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_queue	Pointer to the queue.
[in]	p_item	Pointer to the item.

Return values

Pointer

to 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_queue

Queue to get and remove the head item from.

Return values

Pointer

to 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_queue	Queue to push the item to.
[in]	p_item	Item 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_queue	Queue to push the item to.
[in]	p_item	Item 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_queue	Queue to push the item to.
[in]	p_item	Item to be pushed.
[in]	predicate	Predicate to be used to find the insertion position.

Return values

true	The 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_queue	Queue to push item to.
[in]	p_item	Item to be pushed.
[in]	predicate	Predicate 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_queue	Queue to remove the item from.
[in]	p_item	Item 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_queue	Queue to remove the item from.
[in]	p_after_item	Next 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_queue

Queue to work with.

Return values

Number

of items currently inserted into the queue.