prg_list_elems_copy()

Abstract

Copies the contents of a source list into a destination list (source elements allocated by Riverbed APIs).

Syntax

prg_list_elems_copy (from_list_ptr, to_list_ptr)
Argument Type Description
from_list_ptr PrgT_List * pointer to the source list
to_list_ptr PrgT_List * pointer to the destination list.
A pointer to a list can be obtained from several functions: an empty list can be originally obtained from prg_list_create(), a list representing the contents of a file can be obtained from prg_gdf_read(), or a list can be allocated by user code and initialized via prg_list_init().

Return Type

void

No return value.

prg_list_funcs.h

Example:

/** 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);

Details

The element-copying operations performed by this function rely on the fact that the elements in the originating list pointed to by from_list_ptr, are allocated via known methods such as prg_mem_alloc(), prg_str_decomp(), or prg_gdf_read(). Elements that are allocated via interfaces other than those provided by the Program Library cannot be copied because their size is unknown. If such elements are encountered an error will be generated. There is no requirement that the various list elements be of the same type or size.

This function cannot merge the source list elements into the destination list; instead, it will replace any contents of the destination list with the contents of the source list. The replacement of the destination list contents is performed by initializing the destination list before element copying proceeds. Because list initialization does not deallocate existing list contents, we recommend that prg_list_free() be applied to the destination list before prg_list_elems_copy() is invoked, if the destination list contains elements and has been initialized at some prior time.

Elements that contain pointers to other data structures can be copied via this function, but the structures referenced by the pointers are not copied by the transfer. This does not cause problems if the structures referenced by the list copy elements are not modified. However, if modifications are performed on the structures through one copy’s elements, all copies are affected. If this is undesired, the user’s process code should scan through the original and copy lists in tandem, individually copying over subsidiary data structures.

WARNING: This function is MT unsafe, as described in “Multi-Threading Safety“ on page 11. Access to shared lists must be externally serialized.

Purpose:

Provides a mechanism for producing a copy of a list. This is useful, for example, when a list needs to be shared by more than one process, and the sharing processes will modify their local copies in different ways. A typical example is a list containing routing information. Each node may need to create a copy of the original list, and the copies may need to be maintained independently to allow differences at each node.

Errors:

  • Program Abort: Segmentation violation. (due to invalid list pointer(s), malformed lists, or the presence in the list of invalid element addresses).
  • Recoverable Error: Allocation of memory failed.

Reference:

  • use prg_list_free() to clear out any contents of the destination list before invoking this function
  • use prg_list_size() to determine if the destination list has any contents
  • Use the KP prg_list_transfer() to copy a source list whose elements were allocated by non-Riverbed memory allocation routines

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