op_sar_buf_destroy()
Abstract
Deallocates the specified buffer, releasing associated memory resources for other purposes.
Syntax
op_sar_buf_destroy (sb_hndl)
| Argument | Type | Description |
|---|---|---|
sb_hndl |
Sbhandle |
handle identifying the buffer-of-interest [This value can identify any of the three Sar buffer types: segmentation, reassembly, or resegmentation. A Sar buffer handle is obtained when a buffer is created via the KP op_sar_buf_create().] |
Return Type
void
No return value.
Example
/* Get the handle for the event’s ICI. */
iciptr = op_intrpt_ici ();
/* Extract the request type. */
op_ici_attr_get (iciptr, "svc_request", &svc_req);
/* Request is for closing a connection */
if (svc_req == GP_REQ_CONN_CLOSE)
{
/* Print out the final size of the connection’s buffer. */
printf ("Connection #%d closing down; final buffer size is %d bytes.\n",
conn_ptr->id, op_sar_buf_size (conn_ptr->sbh) / 8);
/* Deallocate the reassembly buffer in use by the connection. */
op_sar_buf_destroy (conn_ptr->sbh);
/* Deallocate the connection data structure. */
op_prg_mem_free (conn_ptr);
}
Details
This KP can be used to deallocate all three types of Sar buffer: segmentation, resegmentation, and reassembly. Invocation of this KP should only occur after the specified buffer is accessed for the last time. As soon as an invocation of this KP returns, the specified buffer handle is invalid, and should no longer be referenced.
Destroying a Sar buffer causes all of its data contents to be deallocated, including source packets that are complete, partially reduced by segmentation, or partially reassembled. If a source packet in a buffer has been partially reduced or reassembled, if it has been segmented multiple times in parallel (via op_sar_srcbuf_seg_access()), or if its segments have been copied, then portions of the source packet exist both inside and outside the buffer. Destroying a Sar buffer containing some of the source packet’s data will leave the packet’s segments outside the buffer unaffected; the only ramification of the destroyed buffer on the remaining source packet segments is that a full reassembly of the source packet may not be possible due to the deallocation of segments that were uniquely contained in the destroyed buffer.
Purpose
Provides a mechanism for removing a Sar buffer that will no longer be used, and “recycling” its associated memory resources. This KP is typically called by connection-oriented process models, from the section of the model dealing with connection “tear-down”, since these sections are concerned with freeing resources used by the closing connection. A process model that has a fixed set of Sar buffers during a simulation will typically not need to call this KP, since the buffers will remain an allocated resource of the process until the simulation ends.
Errors
- Standard Sar errors (see Table 15)
- Diagnostic Error: Illegal attempt to deallocate memory. Memory address is NIL.
- Several diagnostic errors that indicate illegal attempts to deallocate memory of various classes (pooled, categorized, and general)
Reference
- Use the KP op_pk_destroy() to deallocate a Sar segment
- Use the KP op_sar_buf_create() to create a Sar buffer
- Use the KP op_sar_buf_print() to print detailed information about a Sar buffer to the standard output
- Use the KP op_sar_buf_size() to determine the number of bits stored in a Sar buffer