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 |
![](../../../Arrow_up.png) |
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 |
![](../../../Arrow_up.png) |
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 |
![](../../../Arrow_up.png) |
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 |
![](../../../Arrow_up.png) |
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 |
![](../../../Arrow_up.png) |
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 |
![](../../../Arrow_up.png) |
// 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 |
![](../../../Arrow_up.png) |
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 |
![](../../../Arrow_up.png) |
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
Runtime Instance Creation |
![](../../../Arrow_up.png) |
// Allocate and initialize a new instance object and return its handle
// Initialize a new instance object inside the provided structure
ARGUMENTS
params
per-instance config params, or NULL to select default values (target-domain only)
eb
active error-handling block, or NULL to select default policy (target-domain only)
Instance Deletion |
![](../../../Arrow_up.png) |
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
// Finalize the instance object inside the provided structure
Queue_dequeue() // instance |
![](../../../Arrow_up.png) |
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
DETAILS
This function removes an element from the front of queue and returns
it. If the queue is empty, the return value of Queue_dequeue() will
be non-NULL, due to the Queue implementation. Use Queue_empty() to
determine whether or not the Queue is empty before calling
Queue_dequeue().
Queue_empty() // instance |
![](../../../Arrow_up.png) |
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 |
![](../../../Arrow_up.png) |
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 |
![](../../../Arrow_up.png) |
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. If the queue is empty, the return value of
Queue_get() will be non-NULL, due to the Queue implementation.
Use Queue_empty() to determine whether or not the Queue is empty before
calling Queue_get().
Queue_getTail() // instance |
![](../../../Arrow_up.png) |
Get the element at the end of the queue (atomically)
ARGUMENTS
handle
handle of a previously-created Queue instance object
RETURNS
pointer to former end element
DETAILS
This function removes the element at the end of queue and returns
a pointer to it. If the queue is empty, the return value of
Queue_getTail() will be non-NULL, due to the Queue implementation.
Use Queue_empty() to determine whether or not the Queue is empty before
calling Queue_getTail().
Queue_head() // instance |
![](../../../Arrow_up.png) |
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.
Due to the Queue implementation, the return value will be non-NULL
if the Queue is empty. Use Queue_empty() to determine whether or
not the Queue is empty before calling Queue_head().
Queue_put() // instance |
![](../../../Arrow_up.png) |
Put element at end of queue (atomically)
ARGUMENTS
handle
handle of a previously-created Queue instance object
elem
pointer to new queue element
Queue_putHead() // instance |
![](../../../Arrow_up.png) |
Put element at the front of the queue (atomically)
ARGUMENTS
handle
handle of a previously-created Queue instance object
elem
pointer to new queue element
Instance Built-Ins |
![](../../../Arrow_up.png) |
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