prg_mem_free()
Abstract
Deallocates a block of memory that was previously allocated.
Syntax
prg_mem_free (ptr)
| Argument | Type | Description |
|---|---|---|
ptr |
void * |
Pointer to the memory block to be deallocated. Pointers passed to this function should generally be restricted to those originally obtained from prg_mem_alloc() (although, as shown in the Example section, prg_gdf_read() also produces a dynamically-allocated data structure that can be deallocated via this function). |
Return Type
void
No return value.
Header
prg_mem_funcs.h
Example
/* open and read in the contents of a GDF file */
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
Memory that is dynamically allocated should be deallocated if it is no longer useful in the simulation or to EMA or ETS program execution, so that it can be recycled for other purposes. Short-lived data structures that are created during simulation or program execution will build up memory usage if not deallocated, and can cause an unnecessary abort due to lack of memory. The user is responsible for ensuring that NIL or uninitialized pointers are not passed to prg_mem_free(). Other invalid pointers include statically declared memory such as global or temporary function variables.
Purpose
Provides a mechanism for recycling dynamically-allocated memory that has finished serving its purpose in the simulation or program execution. The lifecycle of general-purpose dynamically-allocated memory is as follows:
- A block of memory is allocated by
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
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 function to memory allocated via an interface outside the Program Library or to passing a NIL pointer to
prg_mem_free())
Reference
- use
prg_mem_alloc()to allocate a block of memory - use
prg_mem_copy()to copy a block of memory