prg_list_elems_copy()
摘要
将源列表的内容复制到目标列表(源元素由 Riverbed API 分配)。
语法
prg_list_elems_copy (from_list_ptr, to_list_ptr)
| 参数 | 类型 | 说明 |
|---|---|---|
from_list_ptr |
PrgT_List * |
指向源列表的指针 |
to_list_ptr |
PrgT_List * |
指向目标列表的指针。 获取列表指针的途径有多种:空列表可最初由 prg_list_create() 获得,表示文件内容的列表可由 prg_gdf_read() 获得,也可以由用户代码分配列表并通过 prg_list_init() 初始化。 |
返回类型
void
无返回值。
头文件
prg_list_funcs.h
示例:
/** make a copy of the Node information list, and forward across **/
/** the network to a management station **/
/* first, create a new list */
copy_list = prg_list_create ();
/* copy the node info list into the new list */
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 所指向的源列表中的元素是通过已知方法分配的,例如 prg_mem_alloc()、prg_str_decomp() 或 prg_gdf_read()。通过 Program Library 提供的接口之外的其他方式分配的元素无法复制,因为其大小未知。如果遇到此类元素,将产生错误。并不要求列表中的各个元素具有相同的类型或大小。
该函数不能将源列表元素合并到目标列表中;相反,它会用源列表的内容替换目标列表的任何已有内容。对目标列表内容的替换是通过在元素复制开始之前初始化目标列表来完成的。由于列表初始化不会释放已有的列表内容,因此我们建议在对目标列表调用 prg_list_elems_copy() 之前,先对其应用 prg_list_free(),如果目标列表包含元素并且在之前某个时刻已被初始化过的话。
包含指向其他数据结构指针的元素可以通过该函数复制,但指针所引用的结构并不会随复制而复制。如果不修改列表副本元素所引用的结构,这不会造成问题。然而,如果通过某一个副本的元素对结构进行了修改,则所有副本都会受到影响。如果不希望如此,用户的过程代码应当同步地遍历原始列表和副本列表,逐个复制附属的数据结构。
**警告:**该函数 MT 不安全(线程不安全),相关说明见“Multi-Threading Safety“ 第 11 页。对共享列表的访问必须由外部串行化。
用途:
提供了一种生成列表副本的机制。例如,当一个列表需要被多个进程共享、且各共享进程会以不同方式修改各自的本地副本时,这就很有用。一个典型例子是包含路由信息的列表。每个节点可能需要创建原始列表的一份副本,并且各副本可能需要独立维护,以允许各节点存在差异。
错误:
- 程序中止:段违例。(由于列表指针无效、列表畸形,或列表中存在无效的元素地址)。
- 可恢复错误:内存分配失败。
参考:
- 使用
prg_list_free()在调用该函数之前清空目标列表的任何内容 - 使用
prg_list_size()判断目标列表是否有内容 - 使用 KP
prg_list_transfer()复制元素由非 Riverbed 内存分配例程分配的源列表