op_prg_list_free()
Abstract
Deallocates the contents of the specified list, releasing associated memory resources for other purposes.
Note: This KP is a macro call included for backward compatibility only. Use prg_list_free() in new code.
Syntax
op_prg_list_free (list_ptr)
| Argument | Type | Description |
|---|---|---|
ist_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 statically allocated by user code, and initialized via op_prg_list_init().]. |
Return Type
void
No return value.
Example
/* open and read in the contents of a GDF */
list_ptr = op_prg_gdf_read (gdf_file_name);
/* loop through the contents of the GDF contents list, */
/* printing each line */
list_size = op_prg_list_size (list_ptr);
for (i = 0; i < list_size; i++)
printf ("line %d: [%s]\n", i, (char*) op_prg_list_access (list_ptr, i));
/* deallocate the elements on the list */
op_prg_list_free (list_ptr);
/* deallocate the list itself */
op_prg_mem_free (list_ptr);
Details
Deallocating the contents of a list via op_prg_list_free() does not deallocate the list itself (a list is represented by a small data structure). Instead, the list is initialized, and ready for reuse. If the list itself is no longer needed, it can be deallocated using the KP op_prg_mem_free().
This KP is capable only of deallocating elements within the list that have been allocated via methods that are known to the Simulation Kernel. 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 Simulation Kernel include memory allocated via op_prg_mem_alloc(), op_prg_gdf_read(), op_prg_str_decomp(), and op_prg_list_elems_copy().
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 deallocate all the elements in a list when they are no longer useful, in order to recycle their memory. The elements must have been allocated via known Simulation Kernel 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 the KP op_prg_mem_free() to deallocate a list which is no longer useful (after freeing its elements)
- Use the KP op_prg_list_create() to allocate a new, empty list
- Use the KP op_prg_list_init() to prepare a new, empty list or reset an existing list to an empty state