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.
Header
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()andprg_list_elems_copy(), whereas memory allocated viamalloc()is not.
Errors
- Recoverable Error: Request to allocate (<size>) bytes of Prg memory failed.
Reference
- use
prg_mem_free()to deallocate a previously allocated block of memory - use
prg_mem_copy()to copy a block of memory - use
prg_mem_alloc()to allocate a block of memory and clear it