prg_list_create()
Abstract
Allocates a new, empty list.
Syntax
prg_list_create()
| Argument | Type | Description |
|---|---|---|
| no arguments |
Return Type
PrgT_List *
Pointer to the newly-created, empty list. This pointer is usually directly assigned to a variable declared as a PrgT_List *, as shown in the Example section.
Header
prg_list_funcs.h
Example:
/* allocate an empty list */
lptr = prg_list_create ();
/* allocate four parameter block data structures, and insert into list */
temp_ptr = prg_mem_alloc (sizeof (struct parm_block));
prg_list_insert (lptr, temp_ptr, PRGC_LISTPOS_TAIL);
temp_ptr = prg_mem_alloc (sizeof (struct parm_block));
prg_list_insert (lptr, temp_ptr, PRGC_LISTPOS_TAIL);
temp_ptr = prg_mem_alloc (sizeof (struct parm_block));
prg_list_insert (lptr, temp_ptr, PRGC_LISTPOS_TAIL);
temp_ptr = prg_mem_alloc (sizeof (struct parm_block));
prg_list_insert (lptr, temp_ptr, PRGC_LISTPOS_TAIL);
Details
An empty list has no elements in it, but is ready for elements to be inserted, via prg_list_insert(). Elements can be added to the list in any order.
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 obtain a completely fresh list.
This is one of two ways to obtain an empty list. The other method is for user code to allocate a list (either by a statically-allocated variable, or within a dynamically-allocated data structure), and to initialize the list via prg_list_init().
Errors:
- Program Abort: Allocation of memory failed. Unable to create list data structure.
Reference:
- 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 which is no longer useful (after freeing its elements) - use
prg_list_init()to initialize a statically-allocated list before using it