prg_list_init()
Abstract
Initializes an existing list which has been allocated by user code.
Syntax
prg_list_init (list_ptr)
| Argument | Type | Description |
|---|---|---|
list_ptr |
PrgT_List* |
pointer to the list-of-interest. A pointer to a list can be obtained from several functions: an empty list can be obtained from prg_list_create(); a list representing the contents of a file can be obtained from prg_gdf_read(); a list can be allocated by user code and initialized via prg_list_init(). |
Return Type
void
no return value
Header
prg_list_funcs.h
Example:
/* allocate a list */
list_ptr = (PrgT_List *) prg_mem_alloc (sizeof (PrgT_List));
/* initialize a list */
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 */
prg_list_insert (list_ptr, pkptr, PRGC_LISTPOS_TAIL); }
Details
This function sets up initial values within the list data structure, setting it to the empty state. This function must be applied to user-allocated lists (i.e., list pointers that are not obtained from prg_list_create()) before any other prg_list functions are applied to them.
WARNING: This function 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 Program Library dynamically allocate a list via prg_list_create().
Errors:
- Program Abort: Segmentation violation. (due to an illegal list pointer or malformed list)
Reference:
- use
prg_list_create()to have the Program Library allocate a new, empty list - use
prg_list_insert()to insert an element into a list - use
prg_list_free()to remove and deallocate all elements on a list (retaining the list itself) - use
prg_mem_free()to deallocate a list that is no longer useful, after freeing its elements