prg_list_free()
Abstract
Deallocates the contents of the specified list, releasing associated memory resources for other purposes.
Syntax
prg_list_free (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 statically allocated by user code and initialized via prg_list_init(). |
Return Type
void
No return value.
Header
prg_list_funcs.h
Example:
/* open and read in the contents of a GDF */
list_ptr = prg_gdf_read (gdf_file_name);
/* loop through the contents of the GDF contents list, */
/* printing each line */
list_size = prg_list_size (list_ptr);
for (i = 0; i < list_size; i++)
printf ("line %d: [%s]\n", i, (char*) prg_list_access (list_ptr, i));
/* deallocate the elements on the list */
prg_list_free (list_ptr);
/* deallocate the list itself */
prg_mem_free (list_ptr);
Details
Deallocating the contents of a list via prg_list_free() does not deallocate the list itself (a list is represented by a small data structure). Instead, the list is initialized and made ready for reuse. If the list itself is no longer needed, it can be deallocated using prg_mem_free().
This function is capable of deallocating only list elements that have been allocated via methods that are known to the Program Library. For example, elements that are allocated directly via the memory allocator malloc() will not be deallocated and an error message will be issued. Methods that are known to the Program Library include memory allocated via prg_mem_alloc(), prg_gdf_read(), prg_str_decomp(), and prg_list_elems_copy(). To deallocate elements that were allocated by another method, use prg_list_clear().
WARNING: This function is MT unsafe, as described in “Multi-Threading Safety“ on page 11. Access to shared lists must be externally serialized.
Purpose:
Deallocates all the elements in a list when they are no longer useful, releasing memory. The elements must have been allocated via known Program Library interfaces.
Errors:
- Program Abort: Segmentation violation. (due to the presence in the list of unknown memory types or illegal element pointers)
- Program Abort: Bus Error. (due to the presence in the list of unknown memory types or illegal element pointers)
- Diagnostic Error: Unable to deallocate unknown memory type.
Reference:
- use
prg_list_clear()to simply remove list elements without deallocating them, or to remove and deallocate elements using a custom deallocation routine - use
prg_mem_free()to deallocate a list that is no longer useful, after freeing its elements - use
prg_list_create()to allocate a new, empty list - use
prg_list_init()to prepare a new, empty list or reset an existing list to an empty state