module ti.sdo.utils.List
index URL

Doubly Linked List Manager

The List module makes available a set of functions that manipulate List objects accessed through handles of type List_Handle. Each List contains a linked sequence of zero or more elements referenced through variables of type List_Elem, which are typically embedded as the first field within a structure. [ more ... ]
C synopsis target-domain sourced in ti/sdo/utils/List.xdc
#include <ti/sdo/utils/List.h>
Functions
Void
List_construct// Initialize a new instance object inside the provided structure(List_Struct *structP, const List_Params *params);
List_Handle
List_create// Allocate and initialize a new instance object and return its handle(const List_Params *params, Error_Block *eb);
Void
List_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(List_Handle *handleP);
Ptr 
List_dequeue// Get element from front of List (non-atomic)(List_Handle handle);
Void
List_destruct// Finalize the instance object inside the provided structure(List_Struct *structP);
Void 
List_elemClear// Clears a List element's pointers(List_Elem *elem);
Bool 
List_empty// Test for an empty List (atomic)(List_Handle handle);
Void 
List_enqueue// Put element at end of List (non-atomic)(List_Handle handle, List_Elem *elem);
Void 
List_enqueueHead// Put element at head of List (non-atomic)(List_Handle handle, List_Elem *elem);
Ptr 
List_get// Get element from front of List (atomic)(List_Handle handle);
Void 
List_insert// Insert element at into a List (non-atomic)(List_Handle handle, List_Elem *newElem, List_Elem *curElem);
Ptr 
List_next// Return next element in List (non-atomic)(List_Handle handle, List_Elem *elem);
Void
List_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(List_Params *params);
Ptr 
List_prev// Return previous element in List (non-atomic)(List_Handle handle, List_Elem *elem);
Void 
List_put// Put element at end of List (atomic)(List_Handle handle, List_Elem *elem);
Void 
List_putHead// Put element at head of List (atomic)(List_Handle handle, List_Elem *elem);
Void 
List_remove// Remove elem from middle of list (non-atomic)(List_Handle handle, List_Elem *elem);
Functions common to all target instances
List_handle// Convert this instance structure pointer into an instance handle, List_Handle_label// The label associated with this instance object, List_Handle_name// The name of this instance object, List_Object_count// The number of statically-created instance objects, List_Object_first// The handle of the first dynamically-created instance object, or NULL, List_Object_get// The handle of the i-th statically-created instance object (array == NULL), List_Object_heap// The heap used to allocate dynamically-created instance objects, List_Object_next// The handle of the next dynamically-created instance object, or NULL, List_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
List_Module_getMask// Returns the diagnostics mask for this module, List_Module_hasMask// Test whether this module has a diagnostics mask, List_Module_heap// The heap from which this module allocates memory, List_Module_id// Get this module's unique id, List_Module_setMask// Set the diagnostics mask for this module, List_Module_startupDone// Test if this module has completed startup
Typedefs
typedef struct
List_Elem// Opaque List element List_Elem;
typedef List_Object *
List_Handle// Client reference to an instance object;
typedef struct
List_Object// Opaque internal representation of an instance object List_Object;
typedef struct
List_Params// Instance config-params structure ...
typedef struct
List_Struct// Opaque client structure large enough to hold an instance object List_Struct;
 
DETAILS
The List module makes available a set of functions that manipulate List objects accessed through handles of type List_Handle. Each List contains a linked sequence of zero or more elements referenced through variables of type List_Elem, which are typically embedded as the first field within a structure.
All List function are atomic unless noted otherwise in the API descriptions. An atomic API means that the API completes in core functionality without being interrupted. Therefore, atomic APIs are thread-safe. An example is put. Multiple threads can call put at the same time. The threads do not have to manage the synchronization.
The xdc.runtime.Gate.enterSystem/xdc.runtime.Gate.leaveSystem calls are used to make the APIs atomic. This Gate calls internally use xdc.runtime.System's gate.
The List module can be used both as a queue (i.e. First In First Out), as a stack (i.e. Last In First Out), or as a general purpose linked list.
Lists are represented as doubly-linked lists, so calls to next or prev can loop continuously over the List. Refer to next and prev for examples.
LIST AS A QUEUE
To treat the list object as a queue:
  • Use put to put at the tail of the queue
  • Use get to get from the head of the queue
Here is sample code that acts on a List instance (listHandle) as a queue in a FIFO manner.
  List_Elem  elem[4];
  List_Elem *tmpElem;

  // place at the tail of the queue
  for (i = 0; i < 4; i++) {
      List_put(listHandle, &(elem[i]));  
  }

  // remove the buffers from the head
  while((tmpElem = List_get(listHandle)) != NULL) {
      // process tmpElem
  }
LIST AS A STACK
To treat the list object as a stack:
  • Use putHead to put at the top of the stack
  • Use get to get from the top of the stack
Here is sample code that acts on a List instance (listHandle) as a stack in a LIFO manner.
  List_Elem  elem[4];
  List_Elem *tmpElem;

  // push onto the top (i.e. head)
  for (i = 0; i < 4; i++) {
      List_putHead(listHandle, &(elem[i]));
  }

  // remove the buffers in FIFO order.
  while((tmpElem = List_get(listHandle)) != NULL) {
      // process tmpElem
  }
 
struct List_Elem
index URL

Opaque List element

C synopsis target-domain
typedef struct List_Elem List_Elem;
 
DETAILS
A field of this type is placed at the head of client structs.
 
List_elemClear()  // module-wide
index URL

Clears a List element's pointers

C synopsis target-domain
Void List_elemClear(List_Elem *elem);
 
ARGUMENTS
elem — element to be cleared
DETAILS
This API does not removing elements from a List, and should never be called on an element in a List--only on deListed elements.
Module-Wide Built-Ins
index URL

C synopsis target-domain
Types_ModuleId List_Module_id();
// Get this module's unique id
 
Bool List_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle List_Module_heap();
// The heap from which this module allocates memory
 
Bool List_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 List_Module_getMask();
// Returns the diagnostics mask for this module
 
Void List_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
Instance Object Types
index URL

C synopsis target-domain
typedef struct List_Object List_Object;
// Opaque internal representation of an instance object
 
typedef List_Object *List_Handle;
// Client reference to an instance object
 
typedef struct List_Struct List_Struct;
// Opaque client structure large enough to hold an instance object
 
List_Handle List_handle(List_Struct *structP);
// Convert this instance structure pointer into an instance handle
 
List_Struct *List_struct(List_Handle handle);
// Convert this instance handle into an instance structure pointer
Instance Config Parameters
index URL

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

C synopsis target-domain
List_Handle List_create(const List_Params *params, Error_Block *eb);
// Allocate and initialize a new instance object and return its handle
 
Void List_construct(List_Struct *structP, const List_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
index URL

C synopsis target-domain
Void List_delete(List_Handle *handleP);
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
 
Void List_destruct(List_Struct *structP);
// Finalize the instance object inside the provided structure
 
List_dequeue()  // instance
index URL

Get element from front of List (non-atomic)

C synopsis target-domain
Ptr List_dequeue(List_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created List instance object
RETURNS
pointer to former first element or NULL if empty
DETAILS
This function atomically removes the element from the front of a List and returns a pointer to it.
 
List_empty()  // instance
index URL

Test for an empty List (atomic)

C synopsis target-domain
Bool List_empty(List_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created List instance object
RETURNS
TRUE if this List is empty
 
List_enqueue()  // instance
index URL

Put element at end of List (non-atomic)

C synopsis target-domain
Void List_enqueue(List_Handle handle, List_Elem *elem);
 
ARGUMENTS
handle — handle of a previously-created List instance object
elem — pointer to new List element
DETAILS
This function atomically places the element at the end of List.
 
List_enqueueHead()  // instance
index URL

Put element at head of List (non-atomic)

C synopsis target-domain
Void List_enqueueHead(List_Handle handle, List_Elem *elem);
 
ARGUMENTS
handle — handle of a previously-created List instance object
elem — pointer to new List element
DETAILS
This function atomically places the element at the front of List.
 
List_get()  // instance
index URL

Get element from front of List (atomic)

C synopsis target-domain
Ptr List_get(List_Handle handle);
 
ARGUMENTS
handle — handle of a previously-created List instance object
RETURNS
pointer to former first element or NULL if empty
DETAILS
This function atomically removes the element from the front of a List and returns a pointer to it.
 
List_insert()  // instance
index URL

Insert element at into a List (non-atomic)

C synopsis target-domain
Void List_insert(List_Handle handle, List_Elem *newElem, List_Elem *curElem);
 
ARGUMENTS
handle — handle of a previously-created List instance object
newElem — element to insert
curElem — element to insert in front of
DETAILS
This function inserts newElem in the queue in front of curElem. The caller should protect the list from being changed while using this call since it is non-atomic.
To place an elem at the end of the list, use put. To place a elem at the front of the list, use putHead.
 
List_next()  // instance
index URL

Return next element in List (non-atomic)

C synopsis target-domain
Ptr List_next(List_Handle handle, List_Elem *elem);
 
ARGUMENTS
handle — handle of a previously-created List instance object
elem — element in list or NULL to start at the head
RETURNS
next element in list or NULL to denote end
DETAILS
This function returns the next element on a list. It does not remove any items from the list. The caller should protect the list from being changed while using this call since it is non-atomic.
To look at the first elem on the list, use NULL as the elem argument.
This function is useful in searching a list. The following code shows an example. The scanning of a list should be protected against other threads that modify the list.
  List_Elem  *elem = NULL;

  // Begin protection against modification of the list.

  while ((elem = List_next(listHandle, elem)) != NULL) {
      //act elem as needed. For example call List_remove().
  }

  // End protection against modification of the list.
 
List_prev()  // instance
index URL

Return previous element in List (non-atomic)

C synopsis target-domain
Ptr List_prev(List_Handle handle, List_Elem *elem);
 
ARGUMENTS
handle — handle of a previously-created List instance object
elem — element in list or NULL to start at the end (i.e. tail)
RETURNS
previous element in list or NULL to denote no previous elem
DETAILS
This function returns the previous element on a list. It does not remove any items from the list. The caller should protect the list from being changed while using this call since it is non-atomic.
To look at the last elem on the list, use NULL as the elem argument.
This function is useful in searching a list in reverse order. The following code shows an example. The scanning of a list should be protected against other threads that modify the list.
  List_Elem  *elem = NULL;

  // Begin protection against modification of the list.

  while ((elem = List_prev(listHandle, elem)) != NULL) {
      //act elem as needed. For example call List_remove().
  }

  // End protection against modification of the list.
 
List_put()  // instance
index URL

Put element at end of List (atomic)

C synopsis target-domain
Void List_put(List_Handle handle, List_Elem *elem);
 
ARGUMENTS
handle — handle of a previously-created List instance object
elem — pointer to new List element
DETAILS
This function atomically places the element at the end of List.
 
List_putHead()  // instance
index URL

Put element at head of List (atomic)

C synopsis target-domain
Void List_putHead(List_Handle handle, List_Elem *elem);
 
ARGUMENTS
handle — handle of a previously-created List instance object
elem — pointer to new List element
DETAILS
This function atomically places the element at the front of List.
 
List_remove()  // instance
index URL

Remove elem from middle of list (non-atomic)

C synopsis target-domain
Void List_remove(List_Handle handle, List_Elem *elem);
 
ARGUMENTS
handle — handle of a previously-created List instance object
elem — element in list
DETAILS
This function removes an elem from a list. The elem parameter is a pointer to an existing element to be removed from the List. The caller should protect the list from being changed while using this call since it is non-atomic.
Instance Built-Ins
index URL

C synopsis target-domain
Int List_Object_count();
// The number of statically-created instance objects
 
List_Handle List_Object_get(List_Object *array, Int i);
// The handle of the i-th statically-created instance object (array == NULL)
 
List_Handle List_Object_first();
// The handle of the first dynamically-created instance object, or NULL
 
List_Handle List_Object_next(List_Handle handle);
// The handle of the next dynamically-created instance object, or NULL
 
IHeap_Handle List_Object_heap();
// The heap used to allocate dynamically-created instance objects
 
Types_Label *List_Handle_label(List_Handle handle, Types_Label *buf);
// The label associated with this instance object
 
String List_Handle_name(List_Handle handle);
// The name of this instance object
 
XDCscript usage meta-domain sourced in ti/sdo/utils/List.xdc
var List = xdc.useModule('ti.sdo.utils.List');
module-wide constants & types
    var obj = new List.BasicView// ;
        obj.label = String  ...
        obj.elems = Ptr[]  ...
module-wide config parameters
    List.common$// Common module configuration parameters = Types.Common$ undefined;
    List.rovViewInfo//  = ViewInfo.Instance ViewInfo.create;
module-wide functions
    List.elemClearMeta// Clears a List element's pointers(List.Elem* elem) returns Void
per-instance config parameters
    var params = new List.Params// Instance config-params object;
per-instance creation
    var inst = List.create// Create an instance-object(params);
 
 
metaonly struct List.BasicView
index URL
XDCscript usage meta-domain
var obj = new List.BasicView;
 
    obj.label = String  ...
    obj.elems = Ptr[]  ...
 
 
metaonly config List.common$  // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
List.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.
 
metaonly config List.rovViewInfo  // module-wide
index URL
XDCscript usage meta-domain
List.rovViewInfo = ViewInfo.Instance ViewInfo.create;
 
 
metaonly List.elemClearMeta()  // module-wide
index URL

Clears a List element's pointers

XDCscript usage meta-domain
List.elemClearMeta(List.Elem* elem) returns Void
 
ARGUMENTS
elem — element to be cleared
DETAILS
This API is not for removing elements from a List, and should never be called on an element in a List--only on deListed elements.
Instance Config Parameters
index URL

XDCscript usage meta-domain
var params = new List.Params;
// Instance config-params object
Instance Creation
index URL

XDCscript usage meta-domain
var params = new List.Params;
// Allocate instance config-params
params.config =   ...
// Assign individual configs
 
var inst = List.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 Sat, 11 Feb 2012 00:38:14 GMT