prg_mem_alloc_dont_clear()

Abstract

Allocates an uncleared block of memory with the specified size, for general use.

Syntax

prg_mem_alloc_dont_clear (size)
Argument Type Description
size size_t Number of bytes requested for the memory allocation. Typical allocations of memory for data structures can use the C language pseudo-function sizeof() to yield the size of the structure to be allocated, as illustrated in the Example section.

Return Type

void *

Pointer to the allocated block of memory. The constant PRGC_NIL is returned if the memory allocation fails. The allocated block is not initialized and must not be assumed to be zero-filled.

prg_mem_funcs.h

Example

void * copy_mem_ptr;

/* no need to pre-initialize dest memory block as it will be overwritten */
/* by a shallow src memory copy */
copy_mem_ptr = prg_mem_alloc_dont_clear (src_mem_size);

/* shallow copy src memory */
memcpy (copy_mem_ptr, src_mem_ptr, src_mem_size);

Details

Memory that is dynamically allocated should be deallocated if it is no longer useful in the simulation, or EMA or ET executable, so that it can be recycled for other purposes. Short-lived data structures that are created throughout a simulation or program execution will build up memory usage if not deallocated, and can cause an unnecessary abort due to lack of memory.

Memory that is allocated via this function is tracked by the Program Library under the category “prg memory”, and statistics about its usage can be obtained via the OPNET debugger (ODB) commands memstats, memsrc, and memsnk, or the prg_mem_stats_print() function.

This function is frequently used in conjunction with the C language pseudo-function sizeof(), which returns the size in bytes of a data structure specified by name. The example on the previous page illustrates the combined use of prg_mem_alloc_dont_clear() and sizeof().

Purpose

Provides a mechanism to dynamically allocate memory. Typical uses of this would be to create instances of data structures which have finite lifespans (examples would be records which hold parameters of a session, file transfer, etc.). This function is similar to the malloc() function, and is based on it, but adds the following value:

  • If a memory allocation fails due to lack of memory, an error message is automatically printed and logged.
  • The amount of memory being allocated is monitored, for reporting in case of an allocation error or via debugger commands.
  • Memory allocated via this function is suitable for use with other functions in the Prg package such as prg_list_free() and prg_list_elems_copy(), whereas memory allocated via malloc() is not.

Errors

  • Recoverable Error: Request to allocate (<size>) bytes of Prg memory failed.

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