op_prg_mem_copy_create()
Abstract
Allocates a block of memory with a specified size, then copies the contents of a source memory block into the newly allocated memory block.
Note: This KP is a macro call included for backward compatibility only. Use prg_mem_copy_create() in new code.
Syntax
op_prg_mem_copy_create (value, alloc_size)
| Argument | Type | Description |
|---|---|---|
value |
void* |
pointer to the memory to be copied |
alloc_size |
size_t |
number of bytes requested for the memory allocation |
Return Type
void*
Pointer to the allocated block of memory. The constant OPC_NIL is returned if the memory allocation fails.
[This “generic” pointer should be cast into the appropriate data type for further access.]
Example
/* obtain the document request message from the request array */
doc_req_msg = Doc_Req_Array [next_request++];
/* copy the document request message */
doc_req_msg = (Doc_Req_Msg *) op_prg_mem_copy_create (orig_req_msg, sizeof
(Doc_Req_Msg));
/* process the request */
doc_request_message_process (doc_req_msg);
/* store the processed request in the outgoing array */
Doc_Ans_Array [next_answer++] = doc_req_msg;
Details
This KP is frequently used in conjunction with the C language pseudo-function sizeof(), which returns the size (in bytes) of a data structure specified by name. The example illustrates the combined use of op_prg_mem_copy_create() and sizeof().
WARNING: Ignoring the following limitation can lead to simulation errors.
This KP can be applied to data structures or simple data types. However, it 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 which 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.
Also note the information regarding memory management in the KP op_prg_mem_alloc().
Purpose
Provides a mechanism for creating a memory block of a specific size, then copying any type of data structure into the newly allocated memory block.
Errors
- Recoverable Error: Request to allocate (
<size>) bytes failed. - Program Abort: Segmentation violation. (due to invalid pointer argument, or pointer not pointing to a large enough allocated block of memory)
Reference
- Use the KP op_prg_mem_free() to deallocate a block of memory
- Use the KP op_prg_mem_alloc() to allocate a block of memory
- Use the KP op_prg_mem_copy() to copy a block of memory