包概述

本包负责管理列表(list),即有序的数据元素集合。列表具有以下特性:

  • 列表的数据元素可以是简单的 C 数据类型(如 integer 或 double),也可以是复杂的用户自定义数据结构。
  • 列表可以是异构的,即其中包含不同数据类型的元素。
  • 列表的大小不固定,随着新元素的加入可以增长到任意所需的大小。
  • 列表由多个相互以指针链接的数据结构(“单元”,cell)组成。列表的两端称为 head(表头)和 tail(表尾),由存储在名为 List 的外层数据结构中的指针表示。本子包中的函数通过引用列表指针(PrgT_List *)来操作列表。
  • 列表指针可以存储在 PrgT_List * 类型的变量中。这类变量可以在进程模型的临时变量块或状态变量块中局部声明,在进程模型的头部块或外部 C 文件的起始部分全局声明,或者作为外部 C 文件中函数的局部变量、进程模型函数块内的局部变量声明。列表指针可以插入到数据包字段中,从而从一个进程传送到另一个进程。
  • List 子包提供了用于向列表插入元素、从列表删除元素、不删除地访问列表元素以及其他操作的函数。
  • 列表可以是有序的或无序的。可以用两种方式向列表插入元素:
    • prg_list_insert() 将新元素放到列表的指定位置,并使列表的“状态”变为无序。
    • prg_list_insert_sorted() 将新元素放到排序后正确的位置,并保持列表的有序状态。该函数只能用于有序列表。

一般而言,从有序列表中检索元素比从无序列表中检索更快。可以用 prg_list_sort() 对列表排序,或者在必要时用 prg_list_sorted_set() 手动改变列表的状态。

警告: 出于效率考虑,本包中的许多 API 未做成 MT-safe(多线程安全)。因此在并行仿真中,对共享列表的访问必须由外部手段串行化。

图 2 展示了列表的内部内存组织。

图 2:列表的内部内存组织

列表的内部内存组织

列表有两种分配方式:动态分配和静态分配。

动态分配的列表可以在仿真中或在 EMA、ET 程序中按需创建,不再需要时可以释放。它们特别适合在响应动态事件时有条件地组织元素集合(例如把正在接收的同一个数据报的各个分片保存在一起)。动态分配的列表还有一个优点:可以在进程之间迁移。空列表可以用 prg_list_create() 动态分配;当动态分配的列表不再需要时,可以通过 prg_list_clear() 释放(其 dealloc_proc 参数设为 prg_mem_free())。静态分配的列表声明为 PrgT_List 类型的变量,适用于列表的存在可以预知且位置稳定的场合。静态分配的列表在操作之前必须初始化到已知的空状态;这通过 prg_list_init() 完成。

列表创建或初始化之后即可操作:可以在列表的任意位置插入、删除或访问元素。元素位置以数字索引参数传给函数,0 表示列表头部,索引值越大表示元素越靠近列表尾部(同时也提供了用于标识表头和表尾位置的符号常量)。元素可以用 prg_list_insert() 插入,或用 prg_list_insert_tail_unique() 插入到尾部。元素可以用 prg_list_remove() 从列表删除;被删除的元素可以通过返回的指针访问。列表元素可以用 prg_list_access() 访问,而不破坏其列表成员身份或在列表中的位置。两个列表可以用 prg_list_join() 合并。

若要在链表上快速迭代,可以使用一组专门的高效函数:prg_list_cell_data_get()、prg_list_cell_next_get()、prg_list_head_cell_get() 和 prg_list_cell_remove()。

注意: 访问列表时,不要把这些快速函数与随机访问函数混用。

若干函数提供列表所需的实用操作。函数 prg_list_size() 返回列表中的元素个数,常用于确定用 prg_list_access() 扫描列表或用 prg_list_remove() 消耗列表的循环迭代次数。函数 prg_list_sort() 使用用户定义的元素比较过程对列表排序,从而支持基于元素内容的灵活排序方法。函数 prg_list_elems_copy() 将源列表的内容复制到目标列表;这些元素必须是用 Riverbed 内存 API 分配的。prg_list_transfer() 完成同样的工作,但可用于以其他方式(如 malloc())分配内存的情形。最后,当列表内容不再需要时,可以用一个操作 prg_list_free() 将其移除。不过该函数不会释放列表本身,而这可能有必要,也可能没有必要。prg_list_clear() 移除列表的内容,并可选择性地移除列表本身。

本包提供了一组迭代器函数,用于遍历列表的元素。这些函数比其他方法更高效、更方便。将列表附加到迭代器时,请确保迭代过程中列表不发生变化。使用这些函数时,先用 prg_list_iterator_create() 创建迭代器。要遍历列表,用 prg_list_iterator_attach() 将列表附加到迭代器。用 prg_list_iterator_elem_find() 查找特定元素,用 prg_list_iterator_access() 获取按索引指定的元素的地址。遍历结束后,可以用 prg_list_iterator_free() 将列表从迭代器释放。可以用 prg_list_iterator_list_get() 获取与迭代器关联的列表,用 prg_list_iterator_position_get() 获取迭代器在列表中的位置。