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

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_element is the element to be inserted
  • existing_element is the element already in the buffer that insert_element is being compared to
  • existing_queued is when the existing element was enqueued
  • insert_data_ptr is from oms_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.

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · Documentation compiled and provided by Beijing ZNetLink Technology Co., Ltd.

交流群 · QQ Group:OPNET/智网妙算网络仿真交流群(群号 486383494)

原文档 © 2017 Riverbed Technology · 本站为公益翻译,由 AI 辅助完成,请仔细甄别

Original documentation © 2017 Riverbed Technology. Community translation, AI-assisted. Contact: jiazequn@znetlink.com