op_prg_list_insert()
Abstract
Inserts the specified data element into the specified list, at the specified position.
Note: This KP is a macro call included for backward compatibility only. Use prg_list_insert() in new code.
Syntax
op_prg_list_insert (list_ptr, element_ptr, pos_index)
| 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(). |
element_ptr |
void* |
pointer to the element to be inserted Any data types can be elements of a list, including simple data types (such as integers or character strings) and complex data structures. Casting of the element pointer is not necessary. |
pos_index |
int |
numeric position index of the element to be inserted into the list. [Position indices start at 0 at the head, incrementing by one until the tail is reached. You can specify either an explicit numeric position index or the symbolic constants (OPC_LISTPOS_HEAD or OPC_LISTPOS_TAIL.)] |
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
Elements can be inserted into a list in any order, using the pos_index argument to position the insertion. As elements are inserted in a list at positions other than the list tail, elements between the insertion point and the tail will have their position indices shifted up by one.
The special symbolic list positions OPC_LISTPOS_HEAD and OPC_LISTPOS_TAIL can be used to insert elements at the head or the tail of the list. It is recommended that these constants be used whenever possible.
If pos_index is greater than the number of elements currently in the list, the element is simply appended to the end of the list (no additional elements are inserted).
This KP does not guard against redundant insertions of elements into the list. In other words, the same element address is allowed to be present at multiple locations in the list.
Do not store elements represented as temporary variables in a list, because the variable contents will be overwritten. Instead, you should explicitly allocate memory for each element, as follows:
int* i_ptr; /* temporary variable */
i_ptr = (int *) op_prg_mem_alloc (sizeof (int));
*i_ptr = i; /* fill in desired contents of i_ptr */
op_prg_list_insert (list_ptr, i_ptr, pos_index);
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 insert elements into a list. Lists are typically constructed to hold textual information (such as routing or address translation tables), or to hold a set of packets stored temporarily in a processor.
Errors
- Program Abort: Segmentation violation. (due to an illegal list pointer or malformed list)
Reference
- Use the KP op_prg_list_remove() to remove an element from a list
- Use the KP op_prg_list_create() to have the Simulation Kernel allocate a new, empty list
- Use the KP op_prg_list_init() to prepare a new, empty list which has been allocated by user code
- Use the KP op_prg_list_free() to remove and deallocate all elements on a list (retaining the list itself)