op_prg_mem_copy()
Abstract
Copies the contents of a source block of memory into a destination block of memory.
Note: This KP is a macro call included for backward compatibility only. Use prg_mem_copy() in new code.
Syntax
op_prg_mem_copy (from_ptr, to_ptr, size)
| Argument | Type | Description |
|---|---|---|
from_ptr |
void* |
pointer to block of memory to be copied |
to_ptr |
void* |
pointer to block of memory to hold copy [These pointers can point to any data type, from integer to complex data structure. Casting of the passed pointer value is not necessary, because it is performed automatically by the macro that implements the KP. However, both source and destination pointers should point to the same data type, so that the destination block of memory is large enough to contain the source block of memory, without waste.] |
size |
size_t |
size of the block of memory to be copied, in bytes [The size of a data type can be obtained using the C language pseudo-function sizeof(), as illustrated in the Example section.] |
Return Type
void
No return value.
Example
/* receive a packet from the nearest neighbor */
pkptr = op_pk_get (op_intrpt_strm ());
/* extract the log data structure */
op_pk_nfd_get (pkptr, "fd.log", &log_ptr);
/* add information on this node to the log */
log_ptr->node_list [log_ptr->num_nodes] = node_user_id;
log_ptr->num_nodes++;
/* allocate a copy of the log for local use */
local_log_ptr = (Log_DS *) op_prg_mem_alloc (sizeof (Log_DS));
/* produce the copy */
op_prg_mem_copy (log_ptr, local_log_ptr, sizeof (Log_DS));
/* send the packet to the next node */
op_pk_send (pkptr, OUT_STRM);
Details
This KP can be applied to data structures or simple data types that have been dynamically allocated via op_prg_mem_alloc(). It can also be applied to statically defined data structures such as state variables or temporary variables.
WARNING: Ignoring the following limitation can lead to simulation errors.
This KP should be used only on user-defined data structures, not on Riverbed Modeler-defined data structures such as Packet and Distribution. This is because a raw copy operation does not have the sophistication necessary to produce a usable duplicate, given internal data structure accounting and referencing methods.
Data structures that contain pointers to other data structures can be copied using this KP, but the structures referenced by the pointers are not copied by the raw byte transfer. This does not cause problems as long as the subsidiary structures that are referenced are not modified. However, if modifications are made on the subsidiary structures through one copy of the parent structure, all copies are affected. If this is undesired behavior, the user’s process code should scan through the original and copy parent structures, manually copying over subsidiary data structures as well.
Purpose
Provides a mechanism for creating a duplicate of any type of data structure. This is useful when a data structure’s contents are created by one process, but are used by two or more processes.
Errors
- Program Abort: Segmentation violation. (due to invalid pointer arguments, or either pointer not pointing to a large enough allocated block of memory)
- Recoverable Error: Invalid size (
<size>) specified for memory copy.
Reference
- Use the KP op_prg_mem_alloc() to allocate a block of memory into which another block’s contents can be copied
- Use the KP op_prg_mem_free() to deallocate a block of memory