prg_cmo_alloc()
Abstract
Allocates a categorized memory object of the specified type.
Syntax
prg_cmo_alloc (cm_handle, size)
| Argument | Type | Description |
|---|---|---|
cm_handle |
Cmohandle |
Categorized memory handle specifying the type of categorized memory object to be allocated. Categorized memory handles can be obtained via prg_cmo_define(). |
size |
size_t |
Size of the memory block to allocate, in bytes. |
Return Type
void *
Pointer to the allocated categorized memory object (address of the lowest byte). The constant PRGC_NIL is returned if the memory allocation fails.
Header
prg_mem_funcs.h
Example
#include <string.h>
char * copy_host_name (const char * orig_name)
{
static Cmohandle host_cmo = OPC_NIL;
char * new_name;
FIN (copy_host_name);
if (host_cmo == OPC_NIL)
{
/* First invocation, create the category */
host_cmo = prg_cmo_define ("My Host Names");
if (host_cmo == OPC_NIL)
{
op_sim_end ("Unable to create memory category", "", "", "");
}
/* Allocated memory will be filled with original name, */
/* so no need to zero it out. */
prg_cmo_properties_set (host_cmo, PRGC_MEM_DONT_CLEAR);
}
new_name = (char *) prg_cmo_alloc (host_cmo, strlen (orig_name)+1);
if (new_name == OPC_NIL)
{
op_sim_end ("Memory allocation failure", "", "", "");
}
strcpy (new_name, orig_name);
FRET (new_name);
}
Details
Memory that is dynamically allocated should be deallocated if it is no longer useful in the simulation, so that it can be recycled for other purposes. 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.
Memory allocated via prg_cmo_alloc() can be deallocated via prg_mem_free() in the same manner as memory allocated via prg_mem_alloc().
Purpose
Provides a mechanism to dynamically allocate memory that can be tracked during debugging. Each type of categorized memory object can be tracked via the memstats command of the simulation debugger ODB or by the prg_mem_stats_print() function.
Errors
- Recoverable Error: Categorized memory allocation failed due to invalid categorized memory handle. (typically due to the failure of a previous
prg_cmo_define()call)
Reference
- use
prg_cmo_define()to define a new type of categorized memory object or obtain a categorized memory object handle - use
prg_mem_free()to deallocate a categorized memory object, allowing it to be reused - use
prg_mem_alloc()to allocate generic (non-categorized) memory - use
prg_mem_copy()to copy a block of memory