op_prg_list_elems_copy()
摘要
将源列表的内容复制到目标列表(源元素由 Riverbed API 分配)。
注意: 该内核过程是一个仅为向后兼容而保留的宏调用。新代码应使用 prg_list_elems_copy()。
语法
op_prg_list_elems_copy (from_list_ptr, to_list_ptr)
| 参数 | 类型 | 说明 |
|---|---|---|
from_list_ptr |
List* |
指向源列表的指针 |
to_list_ptr |
List* |
指向目标列表的指针 列表指针可以从多个内核过程获得:空列表最初可由 op_prg_list_create() 获得,表示文件内容的列表可由 op_prg_gdf_read() 获得,或者列表可由用户代码分配并通过 op_prg_list_init() 初始化。 |
返回类型
void
无返回值。
示例
/** make a copy of the Node information list, and forward across **/
/** the network to a management station **/
/* first, create a new list */
copy_list = op_prg_list_create ();
/* copy the node info list into the new list */
op_prg_list_elems_copy (ni_list, copy_list);
/* create a packet to convey the list */
pkptr = op_pk_create_fmt ("node_info_xfer");
/* assign the copy list to a packet field */
op_pk_nfd_set (pkptr, "node_info_list", (int) ni_list);
/* forward the packet to the network layer */
op_pk_send (pkptr, NET_LAYER_OUT);
详情
该内核过程执行的元素复制操作依赖于这样一个事实:由 from_list_ptr 指向的源列表中的元素是通过已知方法分配的,例如 op_prg_mem_alloc()、op_prg_str_decomp() 或 op_prg_gdf_read()。通过仿真内核提供的接口之外的其他接口分配的元素无法复制,因为其大小未知。如果遇到此类元素,将会产生错误。不要求列表中的各个元素具有相同的类型或大小。
该内核过程不能将源列表元素合并进目标列表;相反,它会用源列表的内容替换目标列表的任何内容。对目标列表内容的替换是通过在元素复制开始之前初始化目标列表来完成的。由于列表初始化不会释放已有的列表内容,因此建议在调用 op_prg_list_elems_copy() 之前先对目标列表应用内核过程 op_prg_list_free(),但仅当目标列表包含元素并且在先前某个时刻已被初始化时才这样做。
包含指向其他数据结构指针的元素可以通过该内核过程复制,但指针所引用的结构不会随复制操作一起复制。如果列表副本元素所引用的结构不被修改,这不会造成问题。不过,如果通过某一个副本的元素对这些结构进行修改,所有副本都会受到影响。如果不希望如此,用户的进程代码应当同步遍历原始列表和副本列表,逐个复制附属的数据结构。
注意: 该内核过程不是 MT 安全的,如 “Multi-Threading Safety“ 第 11 页所述。对共享列表的访问必须由外部串行化。
用途
提供一种生成列表副本的机制。例如,当一个列表需要被多个进程共享、且共享进程会以不同方式修改各自的本地副本时,这就很有用。一个典型的例子是包含路由信息的列表。每个节点可能需要最初创建原始列表的一个副本,而这些副本随后可能需要独立维护,以允许各节点存在差异。
错误
- 程序中止:段错误。(由于列表指针无效、列表格式错误,或列表中存在无效的元素地址)
- 可恢复错误:内存分配失败。
参考
- 使用内核过程 op_prg_list_free() 在调用该内核过程之前清空目标列表的任何内容
- 使用内核过程 op_prg_list_size() 判断目标列表是否有内容
- 使用内核过程 op_prg_list_transfer() 复制元素由非 Riverbed 内存分配例程分配的源列表