缓冲区管理
缓冲区管理描述了一组例程,用于管理带有大小约束的内存池与缓冲区的层次结构。
缓冲区与池
缓冲区用于存储元素,每个元素以单元来定义。元素和单元实际代表什么,由该包的使用者自行决定。oms_buffer 的一个专用版本(oms_buffer_pk)将元素定义为数据包、单元定义为字节。详见数据包缓冲区函数。
缓冲区由内存池持有。而且,池本身也可以成为更大池的一部分。可以把池和缓冲区看作一棵树:树的根是最外层的主池(master pool),内部节点是子池(subpool),叶子是缓冲区。下图展示了一个包含五个缓冲区和一个子池的主池,该子池本身又包含三个缓冲区和两个子子池。
图 14:缓冲区与池的层次结构

每个池和缓冲区都以元素和单元两个维度定义了最大容量。任何容量都可以用符号常量 OmsC_Buffer_Infinite 定义为无限。但一个元素(缓冲区或池)的最大容量受其所在各池相应容量的约束。而且,一个池中所有包含的缓冲区和子池共享同一块存储空间。因此,如果一个池中有多个缓冲区,且每个缓冲区的容量都等于该池的容量,那么每个缓冲区可存储的数据量就会受到其他缓冲区已存储数据量的限制。另一方面,如果池的容量至少等于其所有缓冲区与子池容量之和,那么一个池的内容不会影响其他池。
缓冲区是有序的。缓冲区的头部是元素索引 0。缓冲区的尾部是索引最大的元素。若一个元素的索引小于另一个元素的索引,则认为前者位于后者之前。
缓冲区与池的创建
缓冲区不能独立存在。必须至少有一个池来持有缓冲区。主池是不包含在其他池中的池。反之,子池是包含在另一个池中的池,而那个池本身也可以是子池。
主池的创建
创建主池时,必须提供一组适用于该池中元素和单元的参数。这些参数适用于主池包含的所有子池和缓冲区,其定义见下表。这些参数的实际 C 类型请参见 oms_buffer_pool_create()。
表 5:主池中元素与单元的定义参数
| 参数 | 用途 |
|---|---|
| size procedure | 返回一个元素的大小(以单元计) |
| destroy procedure | 销毁一个元素 |
| trace procedure | 返回一个元素的字符串表示 |
| trace strings | 定义元素和单元所代表内容的英文表示(单数和复数形式)(例如 “packet”、“packets”、“byte”、“bytes”) |
元素和单元的最大尺寸是主池中任何缓冲区或子池的总体最大约束。两者中的任意一个都可以定义为无限,表示不施加逻辑限制。当然,计算机中实际可用的物理内存会对实际可存储的最大元素数量施加某种限制。
子池与缓冲区的创建
如上所述,为主池定义元素和单元的参数适用于该主池包含的所有子池和缓冲区。因此,创建子池或缓冲区时无需重复这些参数。
可以根据可用的物理内存,随时创建额外的子池和缓冲区。
元素插入
将元素插入缓冲区取决于两个阶段的成败。
插入阶段 1:基于用户的可接受性检查
该阶段是可选的。只有当创建缓冲区的函数包含了插入准则函数参数(insert_proc)时才会发生。该参数的说明请参见 oms_buffer_create()。如果关联了这样的函数,缓冲区会反复调用它,以便将待插入的元素与缓冲区中当前已有的元素进行比较,从该缓冲区的尾部(最近插入的元素)开始。
插入准则函数具有如下原型:
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);
其中:
insert_element是待插入的元素existing_element是缓冲区中已有的、正在与insert_element比较的元素existing_queued是已有元素入队的时间insert_data_ptr来自oms_buffer_enqueue()调用
该函数的返回值是下列符号值之一。
表 6:OmsT_Buffer_Insert 函数的可能返回值
| 值 | 含义 |
|---|---|
| OmsC_Buffer_Insert_Before | 停止遍历已有元素,并尝试将新元素插入到最后检查的那个元素之前(更靠近缓冲区头部)。 |
| OmsC_Buffer_Insert_After | 停止遍历已有元素,并尝试将新元素插入到最后检查的那个元素之后(更靠近缓冲区尾部)。 |
| OmsC_Buffer_Insert_Continue | 继续处理缓冲区中的下一个元素(如果存在)。 |
| OmsC_Buffer_Insert_Ignore_Element | 停止遍历已有元素并使插入调用失败,因为新元素根本不应被插入。 |
| OmsC_Buffer_Insert_Elements_Overflow | 停止遍历已有元素并使插入调用失败,因为没有足够的空闲空间(以元素计)来插入新元素。 |
| OmsC_Buffer_Insert_Units_Overflow | 停止遍历已有元素并使插入调用失败,因为没有足够的空闲空间(以单元计)来插入新元素。 |
最后两个返回值仅在插入准则函数也执行自己的大小约束检查时才会使用。该检查通常在阶段 2 中进行,如下所述。
插入阶段 2:基于缓冲区的存储空间检查
如果插入准则函数表明应当插入该元素(或者因为缓冲区没有关联这样的函数而跳过了阶段 1),oms_buffer 包会检查缓冲区是否有足够的空闲空间以允许插入该元素。必须为该元素以及该元素包含的单元数量提供足够的空间。如果存在足够的空间,则将该元素插入缓冲区:要么插入到尾部(未使用插入准则函数时),要么根据插入准则函数的结果决定位置。
插入返回值
oms_buffer_enqueue() 调用的结果是下列符号值之一,指示成功或失败。若失败,会指出失败的原因。
表 7:oms_buffer_enqueue() 的可能返回值
| 值 | 含义 |
|---|---|
| OmsC_Buffer_Enqueue_Success | 元素已成功插入。 |
| OmsC_Buffer_Enqueue_Units_Overflow | 没有足够的空闲单元空间来插入该元素。 |
| OmsC_Buffer_Enqueue_Elements_Overflow | 没有足够的空闲元素空间来插入该元素。 |
| OmsC_Buffer_Enqueue_Insert_Criteria_Ignore | 插入准则函数返回了 OmsC_Buffer_Insert_Ignore_Element。 |
| OmsC_Buffer_Enqueue_Null_Element | 空元素指针。 |
| OmsC_Buffer_Enqueue_Null_Handle | 无效的缓冲区句柄。 |
| OmsC_Buffer_Enqueue_Memory_Alloc_Failed | 内部内存分配失败。 |
维护的统计量
每个池和缓冲区都可以自动维护一组统计量。如果在创建时通过 OmsT_Buffer_Stat 结构向池或缓冲区提供了有效的 Stathandle,或者使用 oms_buffer_statistic_set() 或 oms_buffer_pool_statistic_set() 提供了有效的 Stathandle,则该统计量会被维护。
与缓冲区关联的统计量在每次有元素插入或移出缓冲区时更新。与池关联的统计量在每次有元素插入或移出该池中某个缓冲区时(直接或间接经由子池)更新。各统计量的定义见下表(并给出其在 OmsT_Buffer_Stat 数组中的对应索引)。
表 8:维护的统计量
| 索引 | 统计量 |
|---|---|
| OmsC_Buffer_Stat_Overflows | 元素被拒绝次数的累计计数。 |
| OmsC_Buffer_Stat_Free_Size_Units | 当前的空闲大小(以单元计)。若最大容量为无限,则不维护该统计量。 |
| OmsC_Buffer_Stat_Free_Size_Elements | 当前的空闲大小(以元素计)。若最大容量为无限,则不维护该统计量。 |
| OmsC_Buffer_Stat_Buffer_Size_Units | 当前的数据量(以单元计)。 |
| OmsC_Buffer_Stat_Buffer_Size_Elements | 当前的数据量(以元素计) |
| OmsC_Buffer_Stat_Incoming_Units | 最近插入元素的大小(以单元计)。 |
| OmsC_Buffer_Stat_Incoming_Elements | 新元素插入的时间。 |
| OmsC_Buffer_Stat_Queuing_Delay | 最近出队的元素在队列中停留的时间。 |
缓冲区与池的销毁
缓冲区与池(主池或子池)可以随时销毁。销毁一个池会销毁该池包含的所有子池或缓冲区。
当缓冲区被销毁时,存储在该缓冲区中的所有元素也会被销毁,销毁时使用为主池指定的销毁过程。
所需文件
此处描述的文件位于 <reldir>/models/std/include 和 <reldir>/models/std/utilities/oms 目录中。
使用缓冲区管理过程的进程模型应至少引用以下两个通用缓冲区管理文件:
- oms_buffer.h。包含用于缓冲区管理的数据类型定义、符号常量和函数原型。
- oms_buffer.ex.c。包含通用缓冲区函数和过程的定义。
请按所需文件中列出的步骤操作。
使用专用版本(oms_buffer_pk)的进程模型还需要引用以下两个额外文件:
- oms_buffer_pk.h。oms_buffer 处理数据包的专用版本。
- oms_buffer_pk.ex.c。包含 oms_buffer 处理数据包的专用版本的定义。
缓冲区函数
实现缓冲区管理(oms_buffer)操作的函数在以下各节中说明。
- 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()