Package Overview
This package is concerned with managing lists, which are ordered collections of data elements. Lists have the following properties:
- List data elements can range from simple C data types (such as integer or double), to complex user-defined data structures.
- Lists can be heterogeneous, in that they contain data elements of different data types.
- Lists are not fixed in size; they can grow to any required size as new elements are added.
- Lists are composed of multiple data structures (“cells”), which are interlinked by pointers. The ends of the list, termed
headandtail, are represented by pointers which are stored in a encompassing data structure of the type List. Lists are manipulated by functions in this sub-package, by referencing list pointers (PrgT_List *). - List pointers can be stored in variables of the
PrgT_List *data type. Such variables can be locally declared in the temporary variable block or state variable block of process models, globally declared in the header block of process models or in the initial portion of external C files, or declared as local variables of functions in external C files or within the process model function block. List pointers can be transferred from one process to another by inserting them into packet fields. - Functions in the List sub-package are available for inserting an element in a list, removing an element from a list, accessing an element in a list without removing it, and other functions.
- Lists can be sorted or unsorted. You can insert an element into a list either of two ways:
prg_list_insert()places the new element into the list at the specified position and changes the ‘state’ of a list to be considered unsorted.prg_list_insert_sorted()places the new element into the list at the correct sorted position and maintains the list’s sorted state. This function can only be called on sorted lists.
In general, retrieving an element from a sorted lists is faster than retrieving it from an unsorted list. You can sort a list with prg_list_sort() or, if necessary, manually change the status of a list with prg_list_sorted_set().
WARNING: For efficiency reasons, many of the APIs in this package have not been made MT-safe. Thus, in parallel simulations, access to shared lists must be externally serialized.
Figure 2 shows the internal memory organization of lists.
Figure 2: Internal Memory Organization of Lists

There are two ways to allocate a list: dynamically or statically.
Dynamically-allocated lists can be created as needed in a simulation or in an EMA or ET program, and can be deallocated when no longer necessary. They are especially useful for conditionally forming collections of elements in response to a dynamic event (for instance, keeping together fragments of a single datagram which is being received). Dynamically allocated lists also have the advantage of being able to migrate from one process to another. An empty list can be dynamically allocated using prg_list_create(); when a dynamically allocated list is no longer necessary, it can be deallocated via prg_list_clear() (with its dealloc_proc argument set to prg_mem_free()). Statically allocated lists are declared as variables of the PrgT_List data type, and can be used whenever a list’s existence is predictable and is stable in location. Statically allocated lists must be initialized to a known, empty state before they are manipulated; this is performed via prg_list_init().
After a list has been created or initialized, it can be manipulated: elements can be inserted, removed, or accessed at any position in the list. The element position is specified as a numeric index argument to functions, with 0 representing the head of the list, and increasing index values representing elements further towards the tail of the list (symbolic constants also are provided for identifying the head and tail positions). Elements can be inserted into a list using prg_list_insert() or inserted at the tail with prg_list_insert_tail_unique(). Elements can be removed from a list using prg_list_remove(); the removed elements can be accessed via the returned pointer. List elements can be accessed using prg_list_access() without disrupting their status as list members or their position in the list. Two lists can be joined with prg_list_join().
For fast iterations over a linked list, you can use a special set of efficient functions: prg_list_cell_data_get(), prg_list_cell_next_get(), prg_list_head_cell_get(), and prg_list_cell_remove().
Note: Do not mix these fast functions with random-access functions when accessing a list.
Several functions perform needed utility operations on lists. The function prg_list_size() returns the number of elements in a list, and is frequently used to determine the number of iterations of a loop which will scan a list using prg_list_access(), or consume a list using prg_list_remove(). The function prg_list_sort() sorts a list using a user-defined element comparison procedure, thus allowing a flexible sorting methodology based on element contents. The function prg_list_elems_copy() copies a source list’s contents into a destination list; the elements must have been allocated using Riverbed memory APIs. prg_list_transfer() does the same, but can be used when memory was allocated by other means (such as malloc()). Finally, when the contents of a list are no longer needed, they can be removed in one operation prg_list_free(). This function does not deallocate the list, however, which might or might not be necessary. prg_list_clear() removes the contents of a list and, optionally, the list itself.
This package provides a set of iterator functions for walking the elements of a list. These functions are more efficient and convenient than alternative methods. When you attach a list to an iterator, be sure the list does not change during the iteration. To use these functions, begin by creating an iterator with prg_list_iterator_create(). To walk a list, attach it to the iterator with prg_list_iterator_attach(). Use prg_list_iterator_elem_find() to find a particular element and prg_list_iterator_access() to get the address of an element specified by index. When you are finished walking the list, you can free it from the iterator with prg_list_iterator_free(). You can get the list associated with an iterator using prg_list_iterator_list_get() and get the position of an iterator in a list with prg_list_iterator_position_get().