op_prg_list_elems_copy()
Abstract
Copies the contents of a source list into a destination list (source elements allocated by Riverbed APIs).
Note: This KP is a macro call included for backward compatibility only. Use prg_list_elems_copy() in new code.
Syntax
op_prg_list_elems_copy (from_list_ptr, to_list_ptr)
| Argument | Type | Description |
|---|---|---|
from_list_ptr |
List* |
pointer to the source list |
to_list_ptr |
List* |
pointer to the destination list A pointer to a list can be obtained from several KPs: an empty list can be originally obtained from op_prg_list_create(), a list representing the contents of a file can be obtained from op_prg_gdf_read(), or a list can be allocated by user code, and initialized via op_prg_list_init(). |
Return Type
void
No return value.
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 = 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);
Details
The element-copying operations performed by this KP rely on the fact that the elements in the originating list, pointed to by from_list_ptr, are allocated via known methods such as op_prg_mem_alloc(), op_prg_str_decomp(), or op_prg_gdf_read(). Elements that are allocated via interfaces other than those provided by the Simulation Kernel 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 KP 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, it is recommended that the KP op_prg_list_free() be applied to the destination list before op_prg_list_elems_copy() is invoked, but only 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 KP, 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.
Note: This KP 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 may be a list containing routing information. Each node may need to initially create a copy of an original list and the copies may then 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 the KP op_prg_list_free() to clear out any contents of the destination list prior to invoking this KP
- Use the KP op_prg_list_size() to determine if the destination list has any contents
- Use the KP op_prg_list_transfer() to copy a source list whose elements were allocated by non-Riverbed memory allocation routines