op_pk_destroy()
Abstract
Deallocates the specified packet, releasing associated memory resources for other purposes.
Syntax
op_pk_destroy (pkptr)
| Argument | Type | Description |
|---|---|---|
pkptr |
Packet* |
pointer to the packet-of-interest [A pointer to a packet can be obtained from many KPs, including op_pk_create(), op_pk_create_fmt(), op_pk_copy(), op_pk_get(), op_subq_pk_access(), and op_subq_pk_remove().] |
Return Type
void
No return value.
Example
Excerpt from: example model (models/std/base); process model (pc_fifo); state (INS_TAIL); enter execs.
/* a new packet has arrived; acquire it */
pkptr = op_pk_get (op_intrpt_strm ());
/* insert the new packet at tail of subqueue 0 */
if (op_subq_pk_insert (0, pkptr, OPC_QPOS_TAIL) != OPC_QINS_OK)
{
/* if the insertion failed, discard the packet */
op_pk_destroy (pkptr);
}
Details
When a specific packet will no longer be accessed (i.e., its fields will not be obtained or assigned, and it will not be sent or delivered to other modules), then it can be removed from circulation. Destroying a packet via this KP removes a packet from circulation, and releases memory resources that were allocated for the packet. Routes associated with the original packet are also destroyed. However, the ICI is not destroyed when the packet is destroyed, since other packets or process models may still have references to the ICI and intend to use its contents. Use op_ici_destroy() to destroy an unneeded ICI.
Once the packet is destroyed, the released memory can be reused to create new packets. A failure to destroy unused packets will result in a build-up of outstanding packets that may eventually cause a simulation to abort if it attains sufficient virtual memory usage and it can no longer satisfy allocation requests for new objects. Both unformatted and formatted packets can be destroyed via this KP.
This function automatically deallocates memory for all structure and packet fields of a packet. However, if op_pk_nfd_get () is used to strip the structure field from the packet before the packet is destroyed, then you must use op_prg_mem_free () to deallocate the structure field memory.
Purpose
Provides a mechanism for “recycling” memory associated with packets which will no longer be used. The Simulation Kernel is free to assign the released memory for other uses as needed by the progressing simulation. This KP should be invoked after a packet has been accessed for the last time. As soon as this KP returns, the specified packet pointer should be considered invalid in the context that made the call (i.e., it can no longer be referenced or passed to KPs).
Errors
- Program Abort: Segmentation violation. (due to an invalid packet pointer, malformed packet, or malformed packet or structure fields within the packet)
- Program Abort: Bus error. (due to an invalid deallocation procedure for a structure in the packet)
- Program Abort: Packet pointer is NIL.
- Program Abort: Packet pointer references destroyed packet.
- Program Abort: Packet pointer references unowned packet (
<pk_id>). - Program Abort: Packet pointer references static packet (
<pk_id>).
Reference
- Use the KPs op_pk_create() and op_pk_create_fmt() to create new packets.
- Use the KPs op_pk_fd_strip() and op_pk_nfd_strip() to remove a single field from a packet.
- Use the KP op_pk_creation_time_get() to determine how long a packet lived (before destroying it)