Detailed Description

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.

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);
}

Unconstrained Functions All functions are unconstrained

Calling Context

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: Hwi: API is callable from a Hwi thread. Swi: API is callable from a Swi thread. Task: API is callable from a Task thread. Main: API is callable during any of these phases: In your module startup after this module is started (e.g. Queue_Module_startupDone() returns true). During xdc.runtime.Startup.lastFxns. During main(). During BIOS.startupFxns. Startup: API is callable during any of these phases: During xdc.runtime.Startup.firstFxns. In your module startup before this module is started (e.g. Queue_Module_startupDone() returns false).

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include <ti/sysbios/runtime/Error.h>

Include dependency graph for Queue.h:

This graph shows which files directly or indirectly include this file:

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 Documentation

§ Queue_Elem

typedef struct Queue_Elem Queue_Elem

Opaque queue element.

A field of this type is placed at the head of client structs.

§ Queue_Struct

typedef Queue_Elem Queue_Struct

§ Queue_Object

typedef Queue_Struct Queue_Object

§ Queue_Handle

typedef Queue_Struct* Queue_Handle

Function Documentation

§ Queue_create()

Queue_Handle Queue_create	(	const Queue_Params *	prms,
		Error_Block *	eb
	)

Create a Queue object.

This function creates a new Queue object.

Parameters

prms	queue parameters
eb	error block

Return values

Queue handle (NULL on failure)

§ Queue_construct()

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.

Parameters

obj	pointer to a Queue object
prms	queue parameters

Return values

Queue handle (NULL on failure)

§ Queue_delete()

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.

Parameters

queue pointer to Task handle

§ Queue_destruct()

void Queue_destruct ( Queue_Struct * obj )

Destruct a queue.

Queue_destruct destructs a Queue object.

Parameters

obj	pointer to Queue object

§ Queue_Params_init()

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.

Parameters

prms	pointer to uninitialized params structure

§ Queue_insert()

void Queue_insert	(	Queue_Elem *	qelem,
		Queue_Elem *	elem
	)

Insert elem in the queue in front of qelem.

Parameters

qelem	element already in queue
elem	element to be inserted in queue

§ Queue_next()

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.

Parameters

qelem element in queue

Return values

next	element in queue

§ Queue_prev()

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.

Parameters

qelem element in queue

Return values

previous element in queue

§ Queue_remove()

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.

Parameters

qelem element in queue

§ Queue_dequeue()

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.

Note: empty Queue as shown in Queue_get() isn't reliable in a multi-threaded system. Thread safety can be achieved as shown below:

key = Hwi_disable();
if ((Queue_Handle)(elem = Queue_dequeue(q)) != q) {
    ` process elem `
}
Hwi_restore(key);

Parameters

queue Queue handle

Return values

pointer to former first element

§ Queue_empty()

bool Queue_empty ( Queue_Handle queue )

Test for an empty queue.

Parameters

queue Queue handle

Return values

true	if this queue is empty

§ Queue_enqueue()

void Queue_enqueue	(	Queue_Handle	queue,
		Queue_Elem *	elem
	)

Insert at end of queue (non-atomically).

Parameters

queue	Queue handle
elem	pointer to an element

§ Queue_get()

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:

if ((Queue_Handle)(elem = Queue_get(q)) != q) {
    ` process elem `
}

Parameters

queue Queue handle

Return values

pointer to former first element

§ Queue_getTail()

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:

if ((Queue_Handle)(elem = Queue_getTail(q)) != q) {
    `process elem`
}

Parameters

queue Queue handle

Return values

pointer to former end element

§ Queue_head()

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:

if ((Queue_Handle)(elem = Queue_head(q)) != q) {

`process elem`

Parameters

queue Queue handle

Return values

pointer to first element

§ Queue_put()

void Queue_put	(	Queue_Handle	queue,
		Queue_Elem *	elem
	)

Put element at end of queue (atomically).

Parameters

queue	Queue handle
elem	pointer to new queue element

§ Queue_putHead()

void Queue_putHead	(	Queue_Handle	queue,
		Queue_Elem *	elem
	)

Put element at the front of the queue (atomically).

Parameters

queue	Queue handle
elem	pointer to new queue element

Detailed Description

Calling Context

Data Structures

Typedefs

Functions

Typedef Documentation

§ Queue_Elem

§ Queue_Struct

§ Queue_Object

§ Queue_Handle

Function Documentation

§ Queue_create()

§ Queue_construct()

§ Queue_delete()

§ Queue_destruct()

§ Queue_Params_init()

§ Queue_insert()

§ Queue_next()

§ Queue_prev()

§ Queue_remove()

§ Queue_dequeue()

§ Queue_empty()

§ Queue_enqueue()

§ Queue_get()

§ Queue_getTail()

§ Queue_head()

§ Queue_put()

§ Queue_putHead()