module ti.sysbios.knl.Queue

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. [ more ... ]
C synopsis target-domain sourced in ti/sysbios/knl/Queue.xdc
#include <ti/sysbios/knl/Queue.h>
Functions
Void
Void
Ptr 
Void
Bool 
Void 
Ptr 
Ptr 
Ptr 
Void 
Ptr 
Void
Ptr 
Void 
Void 
Void 
Functions common to all target instances
Functions common to all target modules
Typedefs
typedef struct
typedef Queue_Object *
typedef struct
typedef struct
typedef struct
 
DETAILS
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
create N N Y Y N
insert Y Y Y Y N
next Y Y Y Y N
Params_init Y Y Y Y N
prev Y Y Y Y N
remove Y Y Y Y N
construct Y Y Y Y N
delete N N Y Y N
dequeue Y Y Y Y N
destruct Y Y Y Y N
empty Y Y Y Y N
enqueue Y Y Y Y N
get Y Y Y Y N
head Y Y Y Y N
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).
 
struct Queue_Elem

Opaque queue element

C synopsis target-domain
typedef struct Queue_Elem {
    Queue_Elem *next;
    Queue_Elem *prev;
} 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

C synopsis target-domain
Void Queue_insert(Queue_Elem *qelem, Queue_Elem *elem);
 
ARGUMENTS
qelem — element already in queue
elem — element to be inserted in queue
 
Queue_next()  // module-wide

Return next element in queue (non-atomically)

C synopsis target-domain
Ptr Queue_next(Queue_Elem *qelem);
 
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)

C synopsis target-domain
Ptr Queue_prev(Queue_Elem *qelem);
 
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)

C synopsis target-domain
Void Queue_remove(Queue_Elem *qelem);
 
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

C synopsis target-domain
Types_ModuleId Queue_Module_id();
// Get this module's unique id
 
Bool Queue_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle Queue_Module_heap();
// 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

C synopsis target-domain
typedef struct Queue_Object Queue_Object;
// Opaque internal representation of an instance object
 
typedef Queue_Object *Queue_Handle;
// Client reference to an instance object
 
typedef struct Queue_Struct Queue_Struct;
// Opaque client structure large enough to hold an instance object
 
Queue_Handle Queue_handle(Queue_Struct *structP);
// Convert this instance structure pointer into an instance handle
 
Queue_Struct *Queue_struct(Queue_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters

C synopsis target-domain
typedef struct Queue_Params {
// Instance config-params structure
    IInstance_Params *instance;
    // Common per-instance configs
} Queue_Params;
 
Void Queue_Params_init(Queue_Params *params);
// Initialize this config-params structure with supplier-specified defaults before instance creation
Runtime Instance Creation

C synopsis target-domain
Queue_Handle Queue_create(const Queue_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
 
Void Queue_construct(Queue_Struct *structP, const Queue_Params *params);
// 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

C synopsis target-domain
Void Queue_delete(Queue_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void Queue_destruct(Queue_Struct *structP);
// Finalize the instance object inside the provided structure
 
Queue_dequeue()  // instance

Remove the element from the front of queue and return elem. 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()

C synopsis target-domain
Ptr Queue_dequeue(Queue_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created Queue instance object
RETURNS
pointer to former first element
 
Queue_empty()  // instance

Test for an empty queue

C synopsis target-domain
Bool Queue_empty(Queue_Handle handle);
 
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)

C synopsis target-domain
Void Queue_enqueue(Queue_Handle handle, Queue_Elem *elem);
 
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)

C synopsis target-domain
Ptr Queue_get(Queue_Handle handle);
 
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

Get the element at the end of the queue (atomically)

C synopsis target-domain
Ptr Queue_getTail(Queue_Handle handle);
 
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

Return element at front of queue

C synopsis target-domain
Ptr Queue_head(Queue_Handle handle);
 
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

Put element at end of queue (atomically)

C synopsis target-domain
Void Queue_put(Queue_Handle handle, Queue_Elem *elem);
 
ARGUMENTS
handle — handle of a previously-created Queue instance object
elem — pointer to new queue element
 
Queue_putHead()  // instance

Put element at the front of the queue (atomically)

C synopsis target-domain
Void Queue_putHead(Queue_Handle handle, Queue_Elem *elem);
 
ARGUMENTS
handle — handle of a previously-created Queue instance object
elem — pointer to new queue element
Instance Built-Ins

C synopsis target-domain
Int Queue_Object_count();
// The number of statically-created instance objects
 
Queue_Handle Queue_Object_get(Queue_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
 
Queue_Handle Queue_Object_first();
// The handle of the first dynamically-created instance object, or NULL
 
Queue_Handle Queue_Object_next(Queue_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle Queue_Object_heap();
// The heap used to allocate dynamically-created instance objects
 
Types_Label *Queue_Handle_label(Queue_Handle handle, Types_Label *buf);
// The label associated with this instance object
 
String Queue_Handle_name(Queue_Handle handle);
// The name of this instance object
 
Configuration settings sourced in ti/sysbios/knl/Queue.xdc
var Queue = xdc.useModule('ti.sysbios.knl.Queue');
module-wide constants & types
    var obj = new Queue.Elem// Opaque queue element;
        obj.next = Queue.Elem*  ...
        obj.prev = Queue.Elem*  ...
module-wide config parameters
per-instance config parameters
    var params = new Queue.Params// Instance config-params object;
per-instance creation
    var inst = Queue.create// Create an instance-object(params);
 
 
struct Queue.Elem

Opaque queue element

Configuration settings
var obj = new Queue.Elem;
 
    obj.next = Queue.Elem*  ...
    obj.prev = Queue.Elem*  ...
 
DETAILS
A field of this type is placed at the head of client structs.
C SYNOPSIS
 
metaonly config Queue.common$  // module-wide

Common module configuration parameters

Configuration settings
Queue.common$ = Types.Common$ undefined;
 
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
Instance Config Parameters

Configuration settings
var params = new Queue.Params;
// Instance config-params object
Static Instance Creation

Configuration settings
var params = new Queue.Params;
// Allocate instance config-params
params.config =   ...
// Assign individual configs
 
var inst = Queue.create(params);
// Create an instance-object
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)
generated on Fri, 10 Jun 2016 23:29:41 GMT