prg_pmo_define_with_props()
Abstract
Defines a new type of pooled memory object with a set of desired properties.
Syntax
prg_pmo_define_with_props (name, size, increment, properties)
| Argument | Type | Description |
|---|---|---|
name |
const char * |
Name of the pooled memory category. This can be a general character string, including white space if desired (maximum length 48 characters). This name is used to identify the pooled memory object type in memory tracking reports and trace statements (for example, the memstats command of ODB or the prg_mem_stats_print() function). |
size |
size_t |
Number of usable bytes of storage contained in each pooled memory object in the category being defined. |
increment |
int |
Number of objects to request from the operating system as a single block when expanding the pool of objects in the category being defined. |
properties |
int |
Properties to set (see Details). |
Return Type
Pmohandle
Pooled memory object handle used to identify the newly defined memory category. This handle may be used to call prg_pmo_alloc() when allocating individual objects.
Header
prg_mem_funcs.h
Example
static Pmohandle ip_addr_mem_pool;
static int ip_pool_setup = OPC_FALSE;
int *ip_addr_ptr;
if (!ip_pool_setup)
{
/* initialize ip addresses memory pool */
/* No need to pre-clean allocated memory as all ip address fields */
/* are set after allocation */
ip_addr_mem_pool = prg_pmo_define_with_props ("IP Address Storage",
sizeof (int), 256, PRGC_MEM_DONT_CLEAR);
ip_pool_setup = OPC_TRUE;
}
ip_addr_ptr = (int *) prg_pmo_alloc (ip_addr_mem_pool);
*ip_addr_ptr = 0;
Details
This function works like prg_pmo_define(), with the addition of the ability to specify properties for the pooled memory object type being defined.
properties must be either 0 or one of the following symbolic constants (or an OR’ed combination of both):
PRGC_MEM_DONT_CLEAR—pooled memory objects of this type will not clear memory when allocatedPRGC_MEM_POOL_DONT_DEALLOC—pooled memory objects of this type will not deallocate a memory block when all objects in the block have been freed
Note: It is possible, but not desirable, to attempt to create a pooled memory category prior to every allocation, because prg_pmo_define_with_props() is computationally demanding relative to prg_pmo_alloc(), which is sufficient for each allocation.
Purpose
Allows a new pooled memory object type to be created so that allocations can be performed via the function prg_pmo_alloc(). The pooled memory object type can have a set of custom properties.
Errors
- Recoverable Error: Initial allocation of object block failed (due to insufficient memory resources)
Reference
- use
prg_pmo_define()to define a new type of pooled memory object or obtain a pooled memory object handle - use
prg_pmo_alloc()to allocate an object using a pooled memory object handle - use
prg_mem_free()to deallocate a pooled memory object, allowing it to be reused - use
prg_mem_alloc()to allocate generic (non-pooled) memory - use
prg_mem_copy()to copy a block of memory