Module to declare the queue API.
More...
|
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...
|
|
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().
#define SYS_QUEUE_FOR_EACH |
( |
|
p_queue, |
|
|
|
p_iterator |
|
) |
| |
Value:
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 *). |
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.
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 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. |
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. |
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. |
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. |
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). |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |
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. |