prg_cmo_define()
Abstract
Defines a new type of categorized memory object and returns a handle to be used when performing allocations of such objects.
Syntax
prg_cmo_define (name)
| Argument | Type | Description |
|---|---|---|
name |
const char * |
Name of the categorized memory type. This may be a general character string, including white space if desired. This name is used to identify the categorized memory object type in memory tracking reports and trace statements (for example, see the memstats command of ODB or the prg_mem_stats_print() function). |
Return Type
Cmohandle
Categorized memory object handle used to identify the newly defined memory type. This handle can be used to call prg_cmo_alloc() when allocating individual objects.
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
The categorized memory handle returned by this function is usually stored in a state variable of a process so that it can be used at anytime thereafter to perform allocations. Multiple processes or sections of user code may separately invoke prg_cmo_define() with the name argument to create a categorized memory type. However, the redundant calls will be detected and be ineffective. In such cases, equivalent handles are returned for each of the calls and the function serves as a rendezvous mechanism, enabling multiple components of a model to share a categorized memory type without requiring global variables.
Note that it is possible, but not desirable, to attempt to create a categorized memory type prior to every allocation, because the function prg_cmo_define() is computationally demanding relative to the function prg_cmo_alloc(), which is sufficient for each allocation.
Purpose
Creates a new categorized memory object type so that allocations can be performed via the function prg_cmo_alloc(). 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
- None.
Reference
- use
prg_cmo_define_with_props()to define a categorized memory object type with custom properties - use
prg_cmo_alloc()to allocate an object using a categorized memory object handle - use
prg_mem_free()to deallocate a categorized memory object - use
prg_mem_alloc()to allocate generic (non-categorized) memory - use
prg_mem_copy()to copy a block of memory