Memory, Categorized Memory, and Pooled Memory Sub-Packages
In Modeler process models, as in many C programs, most of the data storage needs can be met with statically-declared variables (process models can include static declarations in the temporary variable block, state variable block, or header block). However, dynamic allocation of memory from the heap is sometimes required, especially when the memory needs of a process will change depending on the sequence of events to which it responds. Typical uses of dynamic memory in simulations include storing user-defined message data structures, lookup tables for routing or other purposes, and connection or session-oriented records. Management of dynamic memory in Modeler simulations can be performed by the standard library functions malloc() and free(), but it is recommended that the value-added Kernel Procedures in the Memory, CMO, or PMO sub-packages be used instead. These KPs provide additional error and accounting features over the standard functions, which are useful for debugging.
The Memory sub-package includes a KP to allocate a block of memory, op_prg_mem_alloc(), a KP to deallocate a block of memory, op_prg_mem_free(), and a KP to resize an allocated block of memory, op_prg_mem_realloc(). Also provided are KPs to transfer the contents of a source block of memory to a destination block: op_prg_mem_copy() and op_prg_mem_copy_create(). General-purpose blocks of memory of any size (within the resources of the system) can be allocated by op_prg_mem_alloc().
The Categorized Memory (CMO) sub-package manages memory that provides enhanced reporting capabilities over generic memory. With generic memory, all memory usage is mixed together when reported by ODB or prg_mem_stats_print(). Categorized memory enables you to allocate memory in specific categories that are grouped together by name in usage reports. To use categorized memory, you must define a categorized memory object type using op_prg_cmo_define(). This function returns a handle used by op_prg_cmo_alloc() to allocate memory blocks (called categorized memory objects) belonging to the corresponding category. Categorized memory objects that are no longer needed should be destroyed with op_prg_cmo_dealloc(). Each categorized memory object type has a unique name. Categorized memory objects share the name of their category, but can have different block sizes.
The Pooled Memory (PMO) sub-package is provided to handle a particular sub-class of dynamic memory allocations where significant performance improvements can be achieved relative to the general-purpose allocator underlying the Mem package. When it is known that large numbers of allocations will be performed for blocks of a particular size, and in addition that such blocks will routinely be deallocated and allocated again, the Pmo sub-package offers an important performance advantage. Each memory block category, distinguished by the storage size in bytes, is referred to as a pooled memory object type. Each individual allocation yields a pooled memory object. The KP op_prg_pmo_define() is used to define a new pooled memory object type, returning a handle to use in subsequent allocations throughout the simulation. A special data type called Pmohandle is used for these handles. Individual allocations are performed using the KP op_prg_pmo_alloc(), which expects a Pmohandle in order to specify the type of object to return.
Pooled memory object types are defined by a unique pooled memory object name, a size in bytes for each allocated object, and an increment size. The name is used to track memory usage (e.g., via the discrete event simulation debugger ODB) for the various pooled memory object types. The size parameter simply specifies the number of bytes of storage used for each individual pooled memory object in a given category. Finally, the increment size specifies the number of objects that the PMO sub-package should allocate at once when obtaining more memory for the system. The PMO allocator performs fastest when this parameter is set to a high value; however, in situations where memory resources are severely limited, a high increment size may be undesirable because it may unnecessarily consume memory. Although good choices for increment size depend on specific memory allocation and deallocation patterns, values between 25 and 100 are typically appropriate.
To deallocate pooled memory, use op_prg_pmo_dealloc().