op_prg_list_init()
Abstract
Initializes an existing list that has been allocated by user code.
Note: This KP is a macro call included for backward compatibility only. Use prg_list_init() in new code.
Syntax
op_prg_list_init (list_ptr)
| Argument | Type | Description |
|---|---|---|
list_ptr |
List* |
pointer to the list-of-interest [A pointer to a list can be obtained from several KPs: an empty list can be obtained from op_prg_list_create(); a list representing the contents of a file can be obtained from op_prg_gdf_read(); a list can be allocated by user code, and initialized via op_prg_list_init().] |
Return Type
void
No return value.
Example
/* allocate a list */
list_ptr = (List *) op_prg_mem_alloc (sizeof (List));
/* initialize a list */
op_prg_list_init (list_ptr);
/** move the contents of subqueue #0 into the list **/
/* determine the number of packets in the subqueue */
subq_size = op_subq_stat (0, OPC_QSTAT_PKSIZE);
for (i = 0; i < subq_size; i++)
{
/* take a single packet from the subqueue head */
pkptr = op_subq_pk_remove (0, OPC_QPOS_HEAD);
/* insert the packet onto the list tail */
op_prg_list_insert (list_ptr, pkptr, OPC_LISTPOS_TAIL);
}
Details
This KP sets up initial values within the list data structure, setting it to the empty state. This KP must be applied to user-allocated lists (i.e., list pointers that are not obtained from the KP op_prg_list_create()) before any other op_prg_list… KPs are applied to them.
Note: This KP is MT unsafe, as described in “Multi-Threading Safety“ on page 11. Access to shared lists must be externally serialized.
Purpose
Provides a mechanism to prepare a completely fresh list that has been allocated by user code (either by a statically allocated variable, or within a dynamically allocated data structure). This is one of two ways to obtain an empty list; the other way is to have the Simulation Kernel dynamically allocate a list via the KP op_prg_list_create().
Errors
- Program Abort: Segmentation violation (due to an illegal list pointer or malformed list).
Reference
- Use the KP op_prg_list_create() to have the Simulation Kernel allocate a new, empty list
- Use the KP op_prg_list_insert() to insert an element into a list
- Use the KP op_prg_list_free() to remove and deallocate all elements on a list (retaining the list itself)
- Use the KP op_prg_mem_free() to deallocate a list which is no longer useful (after freeing its elements)