List Sub-Package
This sub-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, which are interlinked by pointers. The ends of the list, termed head and tail, are represented by pointers which are stored in a encompassing data structure of the type List. Lists are manipulated by KPs in this sub-package, by referencing list pointers (
List*). - List pointers can be stored in variables of the
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. - KPs 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. The binary search algorithm is used by the
prg_listsub-package to insert elements into a sorted list. - Lists can be sorted or unsorted. You can insert an element into a list either of two ways:
- op_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.
- op_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 list is faster than retrieving it from an unsorted list.
Note: For efficiency reasons, the KPs in this sub-package have not been made MT-safe. Thus, in parallel simulations, access to shared lists must be externally serialized.
Figure 50 shows the internal memory organization of lists:
Figure 50: List Memory Organization

There are two ways to allocate a list: dynamically or statically. Dynamically-allocated lists can be created as needed in a simulation, 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 the KP op_prg_list_create(); when a dynamically allocated list is no longer necessary, it can be deallocated via the KP op_prg_mem_free() (after its elements have been deallocated). Statically allocated lists are declared as variables of the 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 the KP op_prg_list_init().
Once 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 KPs, 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 the KP op_prg_list_insert(). Elements can be removed from a list using the KP op_prg_list_remove(); the removed elements can be accessed via the returned pointer. And list elements can be accessed using the KP op_prg_list_access()) without disrupting their status as list members or their position in the list.
Several KPs are provided to perform needed utility operations on lists. The KP op_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 op_prg_list_access(), or consume a list using op_prg_list_remove(). The KP op_prg_list_sort()) sorts a list using a user-defined element comparison procedure, thus allowing a flexible sorting methodology based on element contents. The KP op_prg_list_elems_copy() copies a source list’s contents into a destination list; the elements must have been allocated using Riverbed memory APIs. op_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 list are no longer needed, they can be removed in one operation via the KP op_prg_list_free(). This KP does not deallocate the list, however, which may or may not be necessary.