op_prg_mem_alloc()

Abstract

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

Note: This KP is a macro call included for backward compatibility only. Use prg_mem_alloc() in new code.

Syntax

op_prg_mem_alloc (size)
Argument Type Description
size size_t number of bytes requested for 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 OPC_NIL is returned if the memory allocation fails.

This “generic” pointer should be cast into the appropriate data type for further access.

Example

/* allocate a document request message */
doc_req_msg = (Doc_Req_Msg *) op_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, so that it can be reused. 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.

Memory that is allocated via this KP is tracked by the Simulation Kernel under the category “prg_mem blocks”. Statistics about its usage can be obtained via the Simulation Debugger (ODB) commands memstats, memsrc, and memsnk.

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

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

Purpose

Provides a mechanism to dynamically allocate memory. Typical uses of this are creating instances of data structures which have finite lifespans (such as records which hold parameters of a session, file transfer, etc.). This KP is similar to the malloc() function, but has the following additional features:

  • 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 error reporting and debugger information.
  • Memory allocated via this KP is suitable for use with other KPs in the Prg package such as op_prg_list_free() and op_prg_list_elems_copy(), whereas memory allocated via malloc() is not.

Errors

  • Recoverable Error: Request to allocate (<size>) bytes 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