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.
Queue_Elem *elem;
for (elem = Queue_head(myQ);
elem != (Queue_Elem *)myQ;
elem = Queue_next(elem)) {
...
}
Below is a simple example of how to create a Queue, enqueue two elements,
and dequeue the elements until the queue is empty:
#include <xdc/std.h>
#include <xdc/runtime/System.h>
#include <ti/sysbios/knl/Queue.h>
typedef struct Rec {
Queue_Elem _elem;
Int data;
} Rec;
Int main(Int argc, Char *argv[])
{
Queue_Handle q;
Rec r1, r2;
Rec* rp;
r1.data = 100;
r2.data = 200;
// create a Queue instance 'q'
q = Queue_create(NULL, NULL);
// enQ a couple of records
Queue_enqueue(q, &r1._elem);
Queue_enqueue(q, &r2._elem);
// deQ the records and print their data values until Q is empty
while (!Queue_empty(q)) {
rp = Queue_dequeue(q);
System_printf("rec: %d\n", rp->data);
}
System_exit(0);
return (0);
}
struct Queue_Elem |
|
Opaque queue element
typedef struct Queue_Elem {
} Queue_Elem;
DETAILS
A field of this type is placed at the head of client structs.
Queue_insert() // module-wide |
|
Insert elem in the queue in front of qelem
ARGUMENTS
qelem
element already in queue
elem
element to be inserted in queue
Queue_next() // module-wide |
|
Return next element in queue (non-atomically)
ARGUMENTS
qelem
element in queue
RETURNS
next element in queue
DETAILS
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.
Queue_prev() // module-wide |
|
Return previous element in queue (non-atomically)
ARGUMENTS
qelem
element in queue
RETURNS
previous element in queue
DETAILS
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.
Queue_remove() // module-wide |
|
Remove qelem from middle of queue (non-atomically)
ARGUMENTS
qelem
element in queue
DETAILS
The qelem parameter is a pointer to an existing element to be removed
from the Queue.
Module-Wide Built-Ins |
|
// Get this module's unique id
Bool Queue_Module_startupDone();
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool Queue_Module_hasMask();
// Test whether this module has a diagnostics mask
Bits16 Queue_Module_getMask();
// Returns the diagnostics mask for this module
Void Queue_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types |
|
typedef struct Queue_Object Queue_Object;
// Opaque internal representation of an instance object
// Client reference to an instance object
typedef struct Queue_Struct Queue_Struct;
// Opaque client structure large enough to hold an instance object
// Convert this instance structure pointer into an instance handle
// Convert this instance handle into an instance structure pointer
Instance Config Parameters |
|
typedef struct Queue_Params {
// Instance config-params structure
// Common per-instance configs
} Queue_Params;
// Initialize this config-params structure with supplier-specified defaults before instance creation
Queue_dequeue() // instance |
|
Remove the element from the front of queue and return elem
ARGUMENTS
handle
handle of a previously-created Queue instance object
RETURNS
pointer to former first element
Queue_empty() // instance |
|
Test for an empty queue
ARGUMENTS
handle
handle of a previously-created Queue instance object
RETURNS
TRUE if this queue is empty
Queue_enqueue() // instance |
|
Insert at end of queue (non-atomically)
ARGUMENTS
handle
handle of a previously-created Queue instance object
elem
pointer to an element
Queue_get() // instance |
|
Get element from front of queue (atomically)
ARGUMENTS
handle
handle of a previously-created Queue instance object
RETURNS
pointer to former first element
DETAILS
This function removes the element from the front of queue and returns
a pointer to it.
Queue_head() // instance |
|
Return element at front of queue
ARGUMENTS
handle
handle of a previously-created Queue instance object
RETURNS
pointer to first element
DETAILS
This function returns a pointer to the element at the front of queue.
The element is not removed from the queue.
Returns pointer to Queue_Object if queue is empty.
Queue_put() // instance |
|
Put element at end of queue (atomically)
ARGUMENTS
handle
handle of a previously-created Queue instance object
elem
pointer to new queue element
Instance Built-Ins |
|
Int Queue_Object_count();
// The number of statically-created instance objects
// The handle of the i-th statically-created instance object (array == NULL)
// The handle of the first dynamically-created instance object, or NULL
// The handle of the next dynamically-created instance object, or NULL
// The heap used to allocate dynamically-created instance objects
// The label associated with this instance object
// The name of this instance object