op_prg_pmo_alloc()
Abstract
Allocates a pooled memory object of the specified type.
Note: This KP is a macro call included for backward compatibility only. Use prg_pmo_alloc() in new code.
Syntax
op_prg_pmo_alloc (pm_handle)
| Argument | Type | Description |
|---|---|---|
pm_handle |
Pmohandle |
Pooled memory handle specifying the type of pooled memory object to be allocated. Pooled memory handles can be obtained via the KP op_prg_pmo_define() |
Return Type
void*
Pointer to the allocated pooled memory object (address of the lowest byte). The constant OPC_NIL is returned if the memory allocation fails.
This “generic” pointer should be cast into the appropriate data type for further access.]
Example
Excerpt from: example model (std/x25); external file x25_funcs.ex.c; function x25_dp_create()
/* Pooled memory is used to allocate data packets since they are frequently created */
/* and destroyed. If the pooled memory object had not yet been defined, do so now, */
/* prior to allocation. */
if (dp_defined == OPC_FALSE)
{
dp_pmh = op_prg_pmo_define ("X25 buffer data packet",
sizeof (X25T_Data_Packet), 32);
/* Prevent redundant definition. */
dp_defined = OPC_TRUE;
}
/* Allocate a new structure to buffer a data packet. */
dp_ptr = (X25T_Data_Packet*) op_prg_pmo_alloc (dp_pmh);
/* Initialize the data structure */
dp_ptr->packet = pkptr;
dp_ptr->frag_size = log_size;
dp_ptr->format = format;
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.
A memory address returned by op_prg_pmo_alloc() may be identical to addresses previously returned by this KP for the same type of pooled memory object. This is due to memory re-use when a deallocation of the memory block occurs via op_prg_mem_free() and another allocation occurs via op_prg_pmo_alloc().
Use of pooled memory is typically recommended in situations where memory blocks of identical size are frequently allocated and deallocated. The pooled memory allocator can take advantage of this allocation/deallocation cycle to perform more efficiently than the generic allocator provided by op_prg_mem_alloc(). It is typically not recommended to use pooled memory to obtain memory that is never deallocated (such as data structures allocated once at the beginning of a simulation).
Memory allocated via op_prg_pmo_alloc() may be deallocated via op_prg_mem_free() in the same manner as memory allocated via op_prg_mem_alloc(). However, note that memory used for an object of a particular type and then deallocated, can only be reissued for an allocation of an object of the same type.
Purpose
Provides an efficient mechanism to dynamically allocate memory when it is known that large number of allocations and deallocations of identically sized blocks will be performed. The generic memory allocator provided by op_prg_mem_alloc() can exhibit progressive slowdown over the course of a simulation if many deallocations are performed. op_prg_pmo_alloc() avoids this problem by retaining a “pool” of deallocated objects so that new allocations are performed quickly.
Pooled memory provides the additional advantage that usage of each type of object can be individually tracked via the memstats command of the simulation debugger ODB.
Errors
- Recoverable Error: Invalid pool memory object handle (typically due to the failure of a previous op_prg_pmo_define() call)
- Recoverable Error: Allocation of object block failed (due to insufficient memory resources)
Reference
- Use the KP op_prg_pmo_define() to define a new type of pooled memory object and/or obtain a pooled memory object handle
- Use the KP op_prg_pmo_dealloc() or op_prg_mem_free() to deallocate a pooled memory object, allowing it to be reused
- Use the KP op_prg_mem_alloc() to allocate generic (non-pooled) memory
- Use the KP op_prg_mem_copy() to copy a block of memory