prg_pmo_alloc()

Abstract

Allocates a pooled memory object of the specified type.

Syntax

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

Return Type

void *

Pointer to the allocated pooled memory object (address of the lowest byte). The constant PRGC_NIL is returned if the memory allocation fails.

prg_mem_funcs.h

Example

/* 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 = 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*) 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 prg_pmo_alloc() may be identical to addresses previously returned by this function for the same type of pooled memory object. This is due to memory re-use when a deallocation of the memory block occurs via prg_mem_free() and another allocation occurs via 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 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 prg_pmo_alloc() may be deallocated via prg_mem_free() in the same manner as memory allocated via prg_mem_alloc(). However, note that memory used for an object of a specific 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 a large number of allocations and deallocations of identically sized blocks will be performed. The generic memory allocator provided by prg_mem_alloc() can exhibit progressive slowdown over the course of a simulation if many deallocations are performed. prg_pmo_alloc() avoids this problem by retaining a “pool” of deallocated objects so that new allocations are performed quickly.

Errors

  • Recoverable Error: Invalid pool memory object handle (typically due to the failure of a previous prg_pmo_define() call)
  • Recoverable Error: Allocation of object block failed (due to insufficient memory resources)

Reference

  • use prg_pmo_define() to define a new type of pooled memory object and/or obtain a pooled memory object handle
  • use prg_mem_free() to deallocate a pooled memory object, allowing it to be reused
  • use prg_mem_alloc() to allocate generic (non-pooled) memory
  • use prg_mem_copy() to copy a block of memory

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