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

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