oms_buffer_pool_create()
Abstract
Creates a top level memory pool.
Syntax
oms_buffer_pool_create (max_units, max_elements, insert_proc, size_proc, destroy_proc, trace_proc, buffer_stats, buffer_pool_name, element_singular_str, elements_plural_str, unit_singular_str, units_plural_str, user_data_ptr, status_ptr)
| Argument | Type | Description |
|---|---|---|
max_units |
double |
maximum number of units that the pool can contain |
max_elements |
double |
maximum number of elements that the pool can contain |
insert_proc |
OmsT_Buffer_Insertion_Criteria_Proc |
function invoked to validate insertion of new element in the pool |
size_proc |
OmsT_Buffer_Element_Size_Proc |
function mapping an element to a number of units |
destroy_proc |
OmsT_Buffer_Element_Destroy_Proc |
function to destroy an element |
trace_proc |
OmsT_Buffer_Element_Trace_Proc |
function to display an element in ODB tracing |
buffer_stats |
OmsT_Buffer_Stats * |
array of statistic handles to be maintained |
buffer_pool_name |
const char * |
name of the pool for ODB tracing |
element_singular_str |
const char * |
string representation of “element” in ODB tracing |
elements_plural_str |
const char * |
string representation of “elements” in ODB tracing |
unit_singular_str |
const char * |
string representation of “unit” in ODB tracing |
units_plural_str |
const char * |
string representation of “units” in ODB tracing |
user_data_ptr |
void * |
user data associated with the pool |
status_ptr |
OmsT_Buffer_Create * |
result of the creation operation |
Return Type
OmsT_Buffer_Pool_Handle
Pool object resulting from the creation, or OPC_NIL if the creation failed.
Details
This function is used to create a new memory pool that can contain subpools or buffers.
The pool maximum capacity is constrained using the max_units and max_elements arguments. These can be positive values (greater than 0), or the symbolic constants OmsC_Buffer_Infinite.
insert_proc is the function to be used to check any new element added to one of the pool’s buffers later on. This can be OPC_NIL (indicating no function is to be invoked) or the address of a user-specified function. See oms_buffer_enqueue() or Element Insertion for details about the function’s API and use. This function is used by default unless a subpool or buffer provides its own version.
Because elements and units are generic concepts, size_proc, destroy_proc, and trace_proc provide the pool with a means of correctly managing these concepts. size_proc returns the number of units for an element. destroy_proc is used to destroy an element stored in the buffer. Finally, trace_proc is used in ODB to provide a string representation of an element. Prototypes are as follows:
double Buffer_Element_Size_Proc(void * element);
void Buffer_Element_Destroy_Proc(void * element);
const char Buffer_Element_Trace_Proc(void * element);
Each pool can automatically update a set of statistics. Which statistics to maintain is specified by passing in an array of OmsT_Buffer_Stats. Each entry indicates if the statistic is to be maintained and the corresponding stat handle. Specifying OPC_NIL for buffer_stats indicates that no statistic should be maintained initially. For more details on these statistics, see Maintained Statistics.
An optional name can be associated with the pool. This is useful only in the context of ODB for tracing operations on that pool. Use OPC_NIL to indicate that no name is provided.
You can also include a set of strings that indicates what an element or unit represents in the context of the pool. An element might represent a packet; a unit might represent a string. Furthermore, you can specify singular or plural versions of these strings, so you can report:
“1 <element_singular_string> was inserted” (singular version)
“the element was 25 <unit_plural_string> long” (plural version)
An arbitrary structure can be associated with the pool. This structure is not used in any way by the oms_buffer package, but can be used by your code as wanted.
If status_ptr is not OPC_NIL, an appropriate value will be filled in to describe the result of the operation. For more details on the possible creation return values, see Buffer and Pool Creation.