Buffer Management
Buffer management describes a set of routines to manage a hierarchy of memory pools and buffers with size constraints.
Buffers and Pools
The buffers are designed to store elements, each element being defined in terms of units. What elements and units actually represent is up to the user of the package. A specialized version of oms_buffer (oms_buffer_pk) defines elements as packets and units as bytes. See Packet Buffer Functions for details.
Buffers are held by memory pools. Furthermore, pools themselves can be part of larger pools. You can visualize pools and buffers as a tree, where the root of the tree is the encompassing master pool, the internal nodes are subpools, and the leaves are buffers. The representation below shows a master pool with five buffers and one subpool, which itself contains three buffers and two sub-subpools.
Figure 14: Hierarchy of Buffers and Pools

Each pool and buffer is defined with a maximum capacity, both in terms of elements and units. Any capacity can be defined as infinite, using the symbolic constant OmsC_Buffer_Infinite. But the maximum capacity of an element (buffer or pool) is bounded by the corresponding capacity of its encompassing pool(s). Furthermore, all contained buffers and subpools of a pool share a common storage space. Therefore, if there are several buffers in a pool and each buffer has a capacity equal to the pool’s capacity, the amount of data that can be stored in each buffer is limited by the amount of data stored in the others. On the other hand, if the pool’s capacity is at least equal to the sum of its buffers’ and subpools’ capacities, the contents of one pool does not affect the others.
Buffers are ordered. The head of the buffer is element index 0. The tail of the buffer is the element with the highest index. An element is considered to be before another if the index of the former is less than the index of the latter.
Buffer and Pool Creation
Buffers cannot exist on their own. You must have at least one pool to hold buffers. A master pool is a pool that is not contained in another pool. Conversely, a subpool is a pool contained in another pool, which itself could also be a subpool.
Master Pool Creation
When creating a master pool, you must provide a set of parameters that apply to the elements and units for that pool. These parameters apply to all the subpools and buffers contained by the master pool and are defined in the table below. See oms_buffer_pool_create() for the actual C types of these parameters.
Table 5: Defining Parameters of Elements and Units in a Master Pool
| Parameter | Purpose |
|---|---|
| size procedure | returns the size (in units) of an element |
| destroy procedure | destroys an element |
| trace procedure | returns a string representative of an element |
| trace strings | defines the English representations (singular and plural) of what elements and units are (e.g., “packet”, “packets”, “byte”, “bytes”) |
The maximum sizes of elements and units are the overall maximum constraints of any buffer or subpool in the master pool. Either of these two can be defined as infinite, indicating that no logical limitation is enforced. Of course, the actual amount of physical memory in the computer will impose some limit on the actual maximum number of elements that can be stored.
Subpool and Buffer Creation
As mentioned above, the parameters that define elements and units for a master pool apply to all subpools and buffers contained by that master pool. Therefore, these parameters do not have to be repeated when creating a subpool or a buffer.
Additional subpools and buffers can be created at any time, based on the available physical memory.
Element Insertion
The insertion of an element into a buffer is conditional on the success of two phases.
Insertion phase 1: User-based check for acceptability
This phase is optional. It will only happen if the function that created the buffer included an insertion criteria function argument (insert_proc). See oms_buffer_create() for a description of this argument. If such a function is associated, it is repeatedly invoked by the buffer to allow for a comparison between the element to insert and the elements currently found in the buffer, starting with the tail of that buffer (the most recently inserted element).
The insertion criteria function has the following prototype:
OmsT_Buffer_Insert OmsT_Buffer_Insertion_Criteria_Proc (
OmsT_Buffer_Handle buffer_handle,
void* insert_element,
void * existing_element,
double existing_queued,
void * insert_data_ptr);
where:
insert_elementis the element to be insertedexisting_elementis the element already in the buffer thatinsert_elementis being compared toexisting_queuedis when the existing element was enqueuedinsert_data_ptris fromoms_buffer_enqueue()call
The return value of the function is one of the following symbolic values.
Table 6: Possible Return Values for OmsT_Buffer_Insert Function
| Value | Meaning |
|---|---|
| OmsC_Buffer_Insert_Before | Stop iterating through the existing elements and attempt to insert the new element before the last one checked (closer to the head of the buffer). |
| OmsC_Buffer_Insert_After | Stop iterating through the existing elements and attempt to insert the new element after the last one checked (closer to the tail of the buffer). |
| OmsC_Buffer_Insert_Continue | Move on to the next element in the buffer (if any). |
| OmsC_Buffer_Insert_Ignore_Element | Stop iterating through the existing elements and fail the insertion call because the new element should not be inserted at all. |
| OmsC_Buffer_Insert_Elements_Overflow | Stop iterating through the existing elements and fail the insertion call because there isn’t any free space (in terms of elements) to insert the new one. |
| OmsC_Buffer_Insert_Units_Overflow | Stop iterating through the existing elements and fail the insertion call because there isn’t any free space (in terms of units) to insert the new one. |
The last two return values are used only if the insertion-criteria function also runs its own size constraint test. This test is usually done in phase 2, as described below.
Insertion phase 2: Buffer-based check for storage space
If the insertion criteria function indicated that the element should be inserted (or phase 1 was skipped because no such function is associated with the buffer), the oms_buffer package checks that the buffer has enough free space to allow the insertion of the element. There must be sufficient space for the element and for the number of units the element contains. If sufficient space exists, the element is inserted in the buffer either at the tail (if no insertion criteria function was used) or based on the outcome of the insertion criteria function.
Insertion return value
The result of an oms_buffer_enqueue() call is one of the following symbolic values, indicating success or failure. If failure, the reason for failure is indicated.
Table 7: Possible Return Values From oms_buffer_enqueue()
| Value | Meaning |
|---|---|
| OmsC_Buffer_Enqueue_Success | The element was successfully inserted. |
| OmsC_Buffer_Enqueue_Units_Overflow | Not enough free unit space to insert the element. |
| OmsC_Buffer_Enqueue_Elements_Overflow | Not enough free element space to insert the element. |
| OmsC_Buffer_Enqueue_Insert_Criteria_Ignore | Insertion criteria function returned OmsC_Buffer_Insert_Ignore_Element. |
| OmsC_Buffer_Enqueue_Null_Element | Null element pointer. |
| OmsC_Buffer_Enqueue_Null_Handle | Invalid buffer handle. |
| OmsC_Buffer_Enqueue_Memory_Alloc_Failed | Internal memory allocation failure. |
Maintained Statistics
Each pool and buffer can automatically maintain a set of statistics. A statistic is maintained if a valid Stathandle was provided to the pool or buffer, either at creation time using an OmsT_Buffer_Stat structure, or using oms_buffer_statistic_set() or oms_buffer_pool_statistic_set().
The statistics associated with a buffer are updated every time an element is inserted into or removed from the buffer. The statistics associated with a pool are updated every time an element is inserted into or removed from one of the buffers in the pool (directly, or indirectly via subpools). The statistics are defined in the following table (with the corresponding index in the OmsT_Buffer_Stat array).
Table 8: Maintained Statistics
| Index | Statistic |
|---|---|
| OmsC_Buffer_Stat_Overflows | Running count of number of times an element was rejected. |
| OmsC_Buffer_Stat_Free_Size_Units | The current amount of free size, in units. This is not maintained if the maximum size is infinite. |
| OmsC_Buffer_Stat_Free_Size_Elements | The current amount of free size, in elements. This is not maintained if the maximum size is infinite. |
| OmsC_Buffer_Stat_Buffer_Size_Units | The current amount of data, in units. |
| OmsC_Buffer_Stat_Buffer_Size_Elements | The current amount of data, in elements |
| OmsC_Buffer_Stat_Incoming_Units | The size of the most recently inserted element in units. |
| OmsC_Buffer_Stat_Incoming_Elements | When a new element was inserted. |
| OmsC_Buffer_Stat_Queuing_Delay | How long the most recently dequeued element stayed in the queue. |
Buffer and Pool Destruction
Buffer and pools (master or subpool) can be destroyed at any time. Destroying a pool destroys all subpools or buffers contained by that pool.
When a buffer is destroyed, all elements stored in that buffer are also destroyed, using the destruction procedure specified for the master pool.
Required Files
The files described here can be found in the <reldir>/models/std/include and <reldir>/models/std/utilities/oms directories.
A process model using the buffer management procedures should reference at least the following two general buffer management files:
- oms_buffer.h. Contains data type definitions, symbolic constants, and function prototypes used for buffer management.
- oms_buffer.ex.c. Contains definitions for the general buffer functions and procedures.
Use the steps outlined in Required Files.
A process model using the specialized version (oms_buffer_pk) also needs to reference these two additional files:
- oms_buffer_pk.h. Specialized version of oms_buffer dealing with packets.
- oms_buffer_pk.ex.c. Contains definitions for the specialized version of oms_buffer dealing with packets.
Buffer Functions
The functions that implement the buffer management (oms_buffer) operations are described in the following sections.
- oms_buffer_access()
- oms_buffer_create()
- oms_buffer_dequeue()
- oms_buffer_destroy()
- oms_buffer_element_find()
- oms_buffer_enqueue()
- oms_buffer_flush()
- oms_buffer_free_elements_get()
- oms_buffer_free_units_get()
- oms_buffer_is_empty()
- oms_buffer_max_elements_get()
- oms_buffer_max_units_get()
- oms_buffer_num_elements_get()
- oms_buffer_num_units_get()
- oms_buffer_parent_pool_get()
- oms_buffer_pool_buffer_get()
- oms_buffer_pool_create()
- oms_buffer_pool_flush()
- oms_buffer_pool_free_elements_get()
- oms_buffer_pool_free_units_get()
- oms_buffer_pool_get()
- oms_buffer_pool_max_elements_get()
- oms_buffer_pool_max_units_get()
- oms_buffer_pool_num_buffers_get()
- oms_buffer_pool_num_elements_get()
- oms_buffer_pool_num_subpools_get()
- oms_buffer_pool_num_units_get()
- oms_buffer_pool_parent_pool_get()
- oms_buffer_pool_report()
- oms_buffer_pool_statistic_get()
- oms_buffer_pool_statistic_set()
- oms_buffer_pool_subpool_get()
- oms_buffer_pool_user_data_get()
- oms_buffer_pool_user_data_set()
- oms_buffer_report()
- oms_buffer_statistic_get()
- oms_buffer_statistic_set()
- oms_buffer_subpool_create()
- oms_buffer_user_data_get()
- oms_buffer_user_data_set()
- oms_buffer_pk_pool_create()