prg_mem_alloc()

Abstract

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

Syntax

prg_mem_alloc (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.

prg_mem_funcs.h

Example

/* allocate a document request message */
doc_req_msg = (Doc_Req_Msg *) prg_mem_alloc (sizeof (Doc_Req_Msg));

/* fill in the message’s fields */
sprintf (doc_req_msg->doc_name, "%s", app_doc_name);
doc_req_msg->priority = STD_PRI;
doc_req_msg->buffer_size = 4 * MBYTE;

/* assign the message to the outgoing packet */
pkptr = op_pk_get (IN_STRM);
op_pk_nfd_set (pkptr, "message_slot", (int) doc_req_msg);
op_pk_send (pkptr, OUT_STRM);

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() and sizeof().

When a block of memory is allocated via prg_mem_alloc(), each byte that it contains is set to zero before its address is returned. This helps to assure behavioral consistency when user-defined logic does not fully initialize allocated structures.

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