op_prg_cmo_alloc()
Abstract
Allocates a categorized memory object of the specified type.
Note: This KP is a macro call included for backward compatibility only. Use prg_cmo_alloc() in new code.
Syntax
op_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 op_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 OPC_NIL is returned if the memory allocation fails.
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 = op_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 *) op_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 op_prg_cmo_alloc() can be deallocated via op_prg_cmo_dealloc().
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 op_prg_cmo_define() call)
Reference
- use op_prg_cmo_define() to define a new type of categorized memory object or obtain a categorized memory object handle
- use op_prg_cmo_dealloc() to deallocate a categorized memory object, allowing it to be reused
- use op_prg_mem_alloc() to allocate generic (non-categorized) memory
- use op_prg_mem_copy() to copy a block of memory