op_strm_flush()
Abstract
Flushes the specified input packet stream, destroying any packets it contains.
Syntax
op_strm_flush (instrm_index)
| Argument | Type | Description |
|---|---|---|
instrm_index |
int |
numeric index of the input stream-of-interest [Input stream indices start at 0 and increment by one. If the constant OPC_STRM_ALL is specified for this argument, all input streams of the module are flushed.] |
Return Type
void
No return value.
Example
/** loop through all input streams, flushing those that have more **/
/** than one packet queued up within them **/
/* determine the number of allocated input streams */
alloc_instrms = op_strm_max_index_in ();
/* loop through each allocated stream */
for (i = 0; i <= alloc_outstrms; i++)
{
/* if an input stream contains more than one packet, drain it completely. */
if (op_strm_pksize (i) > 1)
op_strm_flush (i);
}
Details
Input streams are initially empty. Packets are placed into input streams via two techniques:
- Connected input streams receive packets that have been transferred using the
op_pk_send…()series of KPs, from source modules which are connected through physical packet streams. - Unconnected input streams can only receive packets that have been transferred using the
op_pk_deliver…()series of KPs, from source processors or queues which are not necessarily even in the same node as the destination module.
There are also two techniques for removing packets from input streams:
- Packets can be removed one-by-one using the KP op_pk_get(), and then manipulated by the process algorithms.
- Packets can be destructively removed en masse using
op_strm_flush()when they are no longer useful.
The logical stream index OPC_STRM_ALL may be specified to cause all existing input streams to be flushed.
Purpose
Provides a mechanism to remove all the packets in an input stream. The packets are destroyed in the process, so this operation is only used when the packets in the input stream can be dropped due to some dynamic condition. Typical uses for flushing an input stream include modeling node crashes or reboots, links or link interfaces going down, routing or other network management updates which invalidate currently buffered data, and the closing of a virtual circuit or session with no requirement to deliver currently buffered messages.
Errors
- Program Abort: KP requires process context.
- Program Abort: Allocation of (
<n>) input streams failed. - Recoverable Error: Input stream index (
<strm_index>) is out-of-range.
Reference
- Use the KP op_strm_empty() to determine if an input stream is empty or not
- Use the KP op_strm_pksize() to determine the number of packets queued in an input stream
- Use the KP op_pk_get() to remove the first packet from an input stream, and obtain a pointer to it