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.
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.
Here is sample code that acts on a List instance (listHandle) as a queue
in a FIFO manner.
Here is sample code that acts on a List instance (listHandle) as a stack
in a LIFO manner.
metaonly struct List.BasicView |
 |
XDCscript usage |
meta-domain |
var obj = new List.BasicView;
obj.label = String ...
obj.elems = Ptr[] ...
struct List.Elem |
 |
Opaque List element
typedef struct List_Elem List_Elem;
DETAILS
A field of this type is placed at the head of client structs.
metaonly config List.common$ // module-wide |
 |
Common module configuration parameters
XDCscript usage |
meta-domain |
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 |
 |
XDCscript usage |
meta-domain |
List.elemClear( ) // module-wide |
 |
Clears a List element's pointers
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.
metaonly List.elemClearMeta( ) // module-wide |
 |
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.
module-wide built-ins |
 |
// Get this module's unique id
Bool List_Module_startupDone( );
// Test if this module has completed startup
// 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
per-instance object types |
 |
typedef struct List_Object List_Object;
// Opaque internal representation of an instance object
// Client reference to an instance object
typedef struct List_Struct List_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
per-instance config parameters |
 |
XDCscript usage |
meta-domain |
var params = new List.Params;
// Instance config-params object
params.metaList = Any[] undefined;
//
typedef struct List_Params {
// Instance config-params structure
// Common per-instance configs
} List_Params;
// Initialize this config-params structure with supplier-specified defaults before instance creation
per-instance creation |
 |
XDCscript usage |
meta-domain |
// Allocate instance config-params
params.config = ...
// Assign individual configs
var inst = List.create( params );
// Create an instance-object
// 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)
per-instance deletion |
 |
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
// Finalize the instance object inside the provided structure
List.dequeue( ) // per-instance |
 |
Get element from front of List (non-atomic)
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( ) // per-instance |
 |
Test for an empty List (atomic)
ARGUMENTS
handle
handle of a previously-created List instance object
RETURNS
TRUE if this List is empty
List.enqueue( ) // per-instance |
 |
Put element at end of List (non-atomic)
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( ) // per-instance |
 |
Put element at head of List (non-atomic)
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( ) // per-instance |
 |
Get element from front of List (atomic)
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( ) // per-instance |
 |
Insert element at into a List (non-atomic)
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( ) // per-instance |
 |
Return next element in List (non-atomic)
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( ) // per-instance |
 |
Return previous element in List (non-atomic)
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( ) // per-instance |
 |
Put element at end of List (atomic)
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( ) // per-instance |
 |
Put element at head of List (atomic)
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( ) // per-instance |
 |
Remove elem from middle of list (non-atomic)
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.
per-instance built-ins |
 |
Int List_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