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.

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · 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