SYS/BIOS
7.00
|
Queue Manager.
The Queue module makes available a set of functions that manipulate queue objects accessed through handles of type Queue_Handle. Each queue contains a linked sequence of zero or more elements referenced through variables of type Queue_Elem, which are embedded as the first field within a structure.
In the Queue API descriptions, the APIs which disable interrupts before modifying the Queue are noted as "atomic", while APIs that do not disable interrupts are "non-atomic".
Queues are represented as doubly-linked lists, so calls to Queue_next or Queue_prev can loop continuously over the Queue. The following code demonstrates one way to iterate over a Queue once from beginning to end. In this example, 'myQ' is a Queue_Handle.
Below is a simple example of how to create a Queue, enqueue two elements, and dequeue the elements until the queue is empty:
Unconstrained Functions All functions are unconstrained
Function | Hwi | Swi | Task | Main | Startup |
---|---|---|---|---|---|
Queue_create | N | N | Y | Y | N |
Queue_insert | Y | Y | Y | Y | N |
Queue_next | Y | Y | Y | Y | N |
Queue_Params_init | Y | Y | Y | Y | N |
Queue_prev | Y | Y | Y | Y | N |
Queue_remove | Y | Y | Y | Y | N |
Queue_construct | Y | Y | Y | Y | N |
Queue_delete | N | N | Y | Y | N |
Queue_dequeue | Y | Y | Y | Y | N |
Queue_destruct | Y | Y | Y | Y | N |
Queue_empty | Y | Y | Y | Y | N |
Queue_enqueue | Y | Y | Y | Y | N |
Queue_get | Y | Y | Y | Y | N |
Queue_head | Y | Y | Y | Y | N |
Queue_put | Y | Y | Y | Y | N |
Definitions:
|
Go to the source code of this file.
Data Structures | |
struct | Queue_Elem |
Opaque queue element. More... | |
struct | Queue_Params |
Typedefs | |
typedef struct Queue_Elem | Queue_Elem |
Opaque queue element. More... | |
typedef Queue_Elem | Queue_Struct |
typedef Queue_Struct | Queue_Object |
typedef Queue_Struct * | Queue_Handle |
Functions | |
Queue_Handle | Queue_create (const Queue_Params *prms, Error_Block *eb) |
Create a Queue object. More... | |
Queue_Handle | Queue_construct (Queue_Struct *obj, const Queue_Params *prms) |
Construct a queue. More... | |
void | Queue_delete (Queue_Handle *queue) |
Delete a queue. More... | |
void | Queue_destruct (Queue_Struct *obj) |
Destruct a queue. More... | |
void | Queue_Params_init (Queue_Params *prms) |
Initialize the Queue_Params structure with default values. More... | |
void | Queue_insert (Queue_Elem *qelem, Queue_Elem *elem) |
Insert elem in the queue in front of qelem . More... | |
void * | Queue_next (Queue_Elem *qelem) |
Return next element in queue (non-atomically). More... | |
void * | Queue_prev (Queue_Elem *qelem) |
Return previous element in queue (non-atomically). More... | |
void | Queue_remove (Queue_Elem *qelem) |
Remove qelem from middle of queue (non-atomically). More... | |
void * | Queue_dequeue (Queue_Handle queue) |
Remove the element from the front of queue and return elem (non- atomically). More... | |
bool | Queue_empty (Queue_Handle queue) |
Test for an empty queue. More... | |
void | Queue_enqueue (Queue_Handle queue, Queue_Elem *elem) |
Insert at end of queue (non-atomically). More... | |
void * | Queue_get (Queue_Handle queue) |
Get element from front of queue (atomically). More... | |
void * | Queue_getTail (Queue_Handle queue) |
Get the element at the end of the queue (atomically). More... | |
void * | Queue_head (Queue_Handle queue) |
Return element at front of queue. (atomically) More... | |
void | Queue_put (Queue_Handle queue, Queue_Elem *elem) |
Put element at end of queue (atomically). More... | |
void | Queue_putHead (Queue_Handle queue, Queue_Elem *elem) |
Put element at the front of the queue (atomically). More... | |
typedef struct Queue_Elem Queue_Elem |
Opaque queue element.
A field of this type is placed at the head of client structs.
typedef Queue_Elem Queue_Struct |
typedef Queue_Struct Queue_Object |
typedef Queue_Struct* Queue_Handle |
Queue_Handle Queue_create | ( | const Queue_Params * | prms, |
Error_Block * | eb | ||
) |
Create a Queue object.
This function creates a new Queue object.
prms | queue parameters |
eb | error block |
Queue | handle (NULL on failure) |
Queue_Handle Queue_construct | ( | Queue_Struct * | obj, |
const Queue_Params * | prms | ||
) |
Construct a queue.
Queue_construct is equivalent to Queue_create except that the Queue_Struct is pre-allocated. See Queue_create() for a description of this API.
obj | pointer to a Queue object |
prms | queue parameters |
Queue | handle (NULL on failure) |
void Queue_delete | ( | Queue_Handle * | queue | ) |
Delete a queue.
Queue_delete deletes a Queue object. Note that Queue_delete takes a pointer to a Queue_Handle which enables Queue_delete to set the Queue_handle to NULL.
queue | pointer to Task handle |
void Queue_destruct | ( | Queue_Struct * | obj | ) |
Destruct a queue.
Queue_destruct destructs a Queue object.
obj | pointer to Queue object |
void Queue_Params_init | ( | Queue_Params * | prms | ) |
Initialize the Queue_Params structure with default values.
Queue_Params_init initializes the Queue_Params structure with default values. Queue_Params_init should always be called before setting individual parameter fields. This allows new fields to be added in the future with compatible defaults – existing source code does not need to change when new fields are added.
prms | pointer to uninitialized params structure |
void Queue_insert | ( | Queue_Elem * | qelem, |
Queue_Elem * | elem | ||
) |
Insert elem
in the queue in front of qelem
.
qelem | element already in queue |
elem | element to be inserted in queue |
void* Queue_next | ( | Queue_Elem * | qelem | ) |
Return next element in queue (non-atomically).
This function returns a pointer to an Elem object in the queue after qelem
. A Queue is represented internally as a doubly-linked list, so 'next' can be called in a continuous loop over the queue. See the module description for an example of iterating once over a Queue.
qelem | element in queue |
next | element in queue |
void* Queue_prev | ( | Queue_Elem * | qelem | ) |
Return previous element in queue (non-atomically).
This function returns a pointer to an Elem object in the queue before qelem
. A Queue is represented internally as a doubly-linked list, so 'prev' can be called in a continuous loop over the queue. See the module description for an example of iterating once over a Queue.
qelem | element in queue |
previous | element in queue |
void Queue_remove | ( | Queue_Elem * | qelem | ) |
Remove qelem from middle of queue (non-atomically).
The qelem
parameter is a pointer to an existing element to be removed from the Queue.
qelem | element in queue |
void* Queue_dequeue | ( | Queue_Handle | queue | ) |
Remove the element from the front of queue and return elem (non- atomically).
This function removes an element from the front of a queue and returns it.
If called with an empty queue, this function will return a pointer to the queue itself.
queue | Queue handle |
pointer | to former first element |
bool Queue_empty | ( | Queue_Handle | queue | ) |
Test for an empty queue.
queue | Queue handle |
true | if this queue is empty |
void Queue_enqueue | ( | Queue_Handle | queue, |
Queue_Elem * | elem | ||
) |
Insert at end of queue (non-atomically).
queue | Queue handle |
elem | pointer to an element |
void* Queue_get | ( | Queue_Handle | queue | ) |
Get element from front of queue (atomically).
This function removes an element from the front of a queue and returns it.
If called with an empty queue, this function will return a pointer to the queue itself. This provides a means for using a single atomic action to check if a queue is empty, and to remove and return the first element if it is not empty:
queue | Queue handle |
pointer | to former first element |
void* Queue_getTail | ( | Queue_Handle | queue | ) |
Get the element at the end of the queue (atomically).
This function removes the element at the end of a queue and returns a pointer to it. If called with an empty queue, this function will return a pointer to the queue itself. This provides a means for using a single atomic action to check if a queue is empty, and to remove and return the last element if it is not empty:
queue | Queue handle |
pointer | to former end element |
void* Queue_head | ( | Queue_Handle | queue | ) |
Return element at front of queue. (atomically)
This function returns a pointer to the element at the front of a queue. The element is not removed from the queue. If called with an empty queue, this function will return a pointer to the queue itself. This provides a means for using a single atomic action to check if a queue is empty, and to return a pointer to the first element if it is not empty:
queue | Queue handle |
pointer | to first element |
void Queue_put | ( | Queue_Handle | queue, |
Queue_Elem * | elem | ||
) |
Put element at end of queue (atomically).
queue | Queue handle |
elem | pointer to new queue element |
void Queue_putHead | ( | Queue_Handle | queue, |
Queue_Elem * | elem | ||
) |
Put element at the front of the queue (atomically).
queue | Queue handle |
elem | pointer to new queue element |