op_prg_pmo_define()

Abstract

Defines a new type of pooled 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_pmo_define() in new code.

Syntax

op_prg_pmo_define (name, size, increment)
Argument Type Description
name const char* Name of the pooled memory category. This can be a general character string, including whitespace if desired (maximum length 48 characters). This name is used to identify the pooled memory object type in memory tracking reports and trace statements (for example, the memstats command of ODB).
size size_t Number of usable bytes of storage contained in each individual pooled memory object in the category being defined.
increment int Number of objects to request from the operating system as a single block when expanding the pool of objects in the category being defined.

Return Type

Pmohandle

Pooled memory object handle used to identify the newly defined memory category. This handle may be used to call op_prg_pmo_alloc() when actually allocating individual objects. If an error occurs during the attempted definition, this function returns the symbolic constant OPC_PMO_INVALID.

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

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).

The pooled memory handle returned by this KP 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 op_prg_pmo_define() with the same name argument in order to create a pooled memory category. However, the redundant calls will be detected and be ineffective. In such cases, equivalent handles are returned for each of the calls, and the KP serves as a rendezvous mechanism, allowing multiple components of a model to share a pooled memory category without requiring global variables. Note that it is possible but not desirable to attempt to create a pooled memory category prior to every allocation, because the KP op_prg_pmo_define() is computationally demanding relative to the KP op_prg_pmo_alloc(), which is sufficient for each allocation.

Purpose

Allows a new pooled memory object type to be created so that allocations can be performed via the KP op_prg_pmo_alloc(). Pooled memory 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: Initial allocation of object block failed (due to insufficient memory resources)

Reference

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · 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