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
- Use the KP op_prg_mem_free() to deallocate a previously allocated block of memory
- Use the KP op_prg_mem_copy() to copy a block of memory