op_strm_empty()
Abstract
Determines if the specified input stream is empty of packets.
Syntax
op_strm_empty (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.] |
Return Type
Boolean
Boolean value indicating whether the specified stream is empty of packets. The value is OPC_TRUE if the specified stream is empty or if a recoverable error occurs, OPC_FALSE otherwise.
Example
/* obtain the object ID of remote telemetry processor */
node_objid = op_id_from_name (0, OPC_OBJTYPE_NODE_FIXED, "tlm_node");
proc_objid = op_id_from_name (node_objid, OPC_OBJTYPE_PROC, "tlm_proc");
/* create a packet */
oc_pkptr = op_pk_create (128);
/* stuff packet with operation code */
op_pk_fd_set (oc_pkptr, 0, OPC_FIELD_TYPE_INTEGER, OPCODE_ACTIVATE, 0);
/* deliver the packet to remote processor under forced conditions */
op_pk_deliver_forced (oc_pkptr, proc_objid, 0);
/* check to see if remote processor responded with quiet packet; */
/* if so, obtain the response code */
if (op_strm_empty (0) == OPC_FALSE)
{
resp_pkptr = op_pk_get (0);
op_pk_fd_get (resp_pkptr, 0, &resp_code);
}
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 the KP
op_strm_flush(), when they are no longer useful.
The KP op_pk_get() can successfully be applied to positive input streams indices that are not connected. The effect of such a call is to pre-allocate input streams from the current maximum stream to the index specified.
This is consistent with the dynamic stream allocation used to support packet deliveries on unoccupied streams.
Purpose
Provides a mechanism to determine if an input stream is empty. This KP is usually invoked as a conditional in a process FSM, or in the conditional clause of an if statement, to bracket a group of statements which should only be executed if a particular input stream contains packets. Typically the bracketed statements will attempt to process one or more of the packets in the input stream, removing them via the KP op_pk_get(). Packets which have been queued in a module's input stream, but which are not read in and processed during the next invocation of the associated process, will continue to be queued until they are removed during a subsequent process invocation.
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_pksize() to determine the number of packets queued in an input stream
- Use the KP op_strm_flush() to remove all packets from an input stream
- Use the KP op_pk_get() to remove the first packet from an input stream, and obtain a pointer to it