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 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.
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.
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.
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
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
Instance Config Parameters |
|
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
Instance Creation |
|
// 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 |
|
// Finalize and free this previously allocated instance object, setting the referenced handle to NULL
// Finalize the instance object inside the provided structure
List_dequeue() // 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() // 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() // 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() // 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() // 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() // 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() // 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() // 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() // 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() // 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() // 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.
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