op_prg_mem_free()
Abstract
Deallocates a block of memory that was previously allocated.
Note: This KP is a macro call included for backward compatibility only. Use prg_mem_free() in new code.
Syntax
op_prg_mem_free (ptr)
| Argument | Type | Description |
|---|---|---|
ptr |
void* |
pointer to the memory block to be deallocated Pointers passed to this KP should generally be restricted to those originally obtained from the KP op_prg_mem_alloc() (although, as shown in the Example section below, op_prg_gdf_read() also produces a dynamically allocated data structure that can be deallocated using this KP). |
Return Type
void
No return value.
Example
/* open and read in the contents of a GDF file */
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
Memory that is dynamically allocated should be deallocated if it is no longer useful in the simulation, so that it can be reused. Short-lived data structures that are created throughout a simulation will build up memory usage if not deallocated, and can cause simulations to unnecessarily abort due to lack of memory.
Purpose
Provides a mechanism for recycling dynamically allocated memory that has finished serving its purpose in the simulation. The life cycle of general-purpose dynamically allocated memory in simulations is as follows:
- A block of memory is allocated by op_prg_mem_alloc(), and is cast into an appropriate data structure.
- Value assignments are performed on the data structure, which is used for data storage or communication.
- After the structure’s role is over, its memory block is deallocated by
op_prg_mem_free().
Errors
- Program Abort: Segmentation violation (due to an invalid ptr argument).
- Diagnostic Error: Unable to deallocate unknown memory type (due to application of this KP to memory allocated via an interface outside the Simulation Kernel).
Reference
- Use the KPs op_prg_cmo_dealloc() or op_prg_pmo_dealloc() to deallocate memory objects of these specific types
- Use the KP op_prg_mem_alloc() to allocate a block of memory
- Use the KP op_prg_mem_copy() to copy a block of memory