Package Overview

In process models, as in many C programs, most 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 simulations can be performed by the standard library functions malloc() and free(), but we recommend that you use the value-added functions in the Memory and Pooled Memory (Mem) package instead. These functions provide additional error and accounting features that are useful for debugging.

The Mem package provides functions for managing several types of memory:

In addition, the Mem package provides a common set of functions for copying, deallocating, and reporting memory statistics. These functions, described in Common Memory Functions, work with all three types of memory.

Generic Memory

Generic memory provides a basic level of improvement over the standard functions malloc() and free() by providing memory with some additional error reporting and debugging abilities. The functions for generic memory are:

Categorized Memory

Categorized memory 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 prg_cmo_define() or prg_cmo_define_with_props(). These functions return a handle used by prg_cmo_alloc() to allocate memory blocks (called categorized memory objects) belonging to the corresponding category.

By default, categorized memory objects are cleared when allocated. If this is not necessary, you can save time by using prg_cmo_define_with_props() with the PRGC_MEM_DONT_CLEAR option to define a categorized memory object type that does not clear memory when objects of that type are allocated.

Each categorized memory object type has a unique name. Categorized memory objects share the name of their category, but can have different block sizes.

Pooled Memory

Pooled memory provides the reporting advantages of categorized memory, plus significant performance improvements for certain situations. Pooled memory can reduce memory allocation time when large numbers of allocations will be performed for blocks of the same size. In addition, the usage of each type of object can be tracked individually by the memstats command of the simulation debugger ODB and by prg_mem_stats_print().

Pooled memory object types are defined with a unique name, object size, and increment count via prg_pmo_define() or prg_pmo_define_with_props(). The define functions return a handle used by prg_pmo_alloc() to allocate pooled memory objects.

Figure 1: Pooled Memory Allocation

Pooled Memory Allocation

The object size specifies the number of bytes of storage used for each pooled memory object in a given category. The increment specifies the number of objects that the Mem package should allocate as a block when obtaining more memory for that category. The Mem package automatically allocates a new block of pooled memory when needed to satisfy an object allocation made via prg_pmo_alloc(), and deallocates a block when all objects in the block have been freed. To deallocate a pooled memory object, use prg_pmo_dealloc().

The pooled memory allocator performs fastest when the increment size is set to a high value; however, in situations where memory resources are severely limited, a high increment size might be undesirable because it could unnecessarily consume memory. Conversely, a low increment size can result in frequent allocation and deallocation of pooled memory blocks, which will cause slower performance. Although good choices for increment size depend on specific memory allocation and deallocation patterns, values between 25 and 100 are typically appropriate.

Pooled memory object types can be defined with prg_pmo_define_with_props() to not clear memory when objects of that type are allocated or to not deallocate memory blocks when all objects in the block have been freed.

Common Memory Functions

Several functions can be used with all three types of memory managed by this package:

  • prg_mem_copy()—copies the contents of a source block of memory into a destination block of memory.
  • prg_mem_copy_create()—allocates a block of memory with the specified size and copies the contents of a source block of memory into the newly allocated block of memory.
  • prg_mem_free()—deallocates a block of memory that was previously allocated.
  • prg_mem_stats_total_usage_get()—gets the total memory usage of a specified sub-category for general, pooled, categorized, or all memory.
  • prg_mem_stats_print()—displays a table with memory usage statistics for objects in the system.

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · Documentation compiled and provided by Beijing ZNetLink Technology Co., Ltd.

交流群 · QQ Group:OPNET/智网妙算网络仿真交流群(群号 486383494)

原文档 © 2017 Riverbed Technology · 本站为公益翻译,由 AI 辅助完成,请仔细甄别

Original documentation © 2017 Riverbed Technology. Community translation, AI-assisted. Contact: jiazequn@znetlink.com