oms_buffer_create()
Abstract
Creates a new buffer inside a specified pool.
Syntax
oms_buffer_create (buffer_pool, max_units, max_elements, insert_proc, buffer_stats, buffer_name, user_data_ptr, status_ptr, elements_factor_proc)
| Argument | Type | Description |
|---|---|---|
buffer_pool |
OmsT_Buffer_Pool_Handle |
buffer pool in which the operation should take place |
max_units |
double |
maximum number of units that can be held by this buffer |
max_elements |
double |
maximum number of elements that can be held by this buffer |
insert_proc |
OmsT_Buffer_Insertion_Criteria_Proc |
function invoked whenever a new element is added to the buffer |
buffer_stats |
OmsT_Buffer_Stats * |
array of statistic handles |
buffer_name |
const char * |
name associated with the buffer for ODB tracing |
user_data_ptr |
void * |
arbitrary user data associated with the buffer |
status_ptr |
OmsT_Buffer_Create * |
indicator of the success or failure (with reason) of the creation of this new buffer |
elements_factor_proc |
OmsT_Buffer_Elements_Factor_Proc |
optional function invoked to determine the number of elements within an element (OPC_NIL if not specified) |
Return Type
OmsT_Buffer_Handle
Created buffer object or OPC_NIL if the operation failed.
Details
The buffer maximum capacity is constrained using the max_units and max_elements arguments. These can be positive values (greater than 0), or one of the symbolic constants OmsC_Buffer_Infinite or OmsC_Buffer_Parent_Limit. If the latter is specified, the buffer will use its parent pool’s constraint. Otherwise, the specified value will indicate the buffer-specific constraint. The buffer constraints must be as strict or stricter than those of its parent or the creation operation will fail.
insert_proc is the function to be used to check any new element added to the buffer later on. This can be OPC_NIL (indicating no function is to be invoked), oms_buffer_pool_criteria_proc (indicating that the function to be used is whatever was specified for the parent pool), or the address of a user-specified function. See oms_buffer_enqueue() or Element Insertion for details about the function’s API and use.
Each buffer can automatically update a set of statistics. The list of 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 statistics should be maintained initially. For more details on these statistics, see Maintained Statistics.
An optional name can be associated with the buffer. This is useful only in the context of ODB for tracing operations on that buffer. Use OPC_NIL to indicate that no name is provided.
An arbitrary structure can be associated with the buffer. 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.
elements_factor_proc is an optional argument specifying a callback used to determine how many elements comprise an element. It is called when inserting or de-queueing an element in a buffer. If this callback is not specified (argument value is OPC_NIL), num_elements will be set to 1 for any element enqueued or dequeued in the buffer. The prototype of this callback is:
int
(*OmsT_Buffer_Elements_Factor_Proc) (void* element);