op_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.
Note: This KP is a macro call included for backward compatibility only. Use prg_cmo_define() in new code.
Syntax
op_prg_cmo_define (name)
| Argument | Type | Description |
|---|---|---|
name |
const char * |
Name of the categorized memory type. This can 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 op_prg_cmo_alloc() when allocating individual objects.
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
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 can separately invoke op_prg_cmo_define() with the same 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.
It is possible, but not desirable, to attempt to create a categorized memory type prior to every allocation. You should avoid doing so because the function op_prg_cmo_define() is computationally demanding relative to the function op_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 op_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 op_prg_cmo_alloc() to allocate an object using 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