op_strm_access()
Abstract
Delivers an access interrupt to the module attached to the specified input stream.
Syntax
op_strm_access (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
Compcode
Completion code indicating if an access interrupt was successfully generated at the module that is the source of the specified input stream.
Example
/** loop through all input streams, generating an access interrupt for each **/
/* determine the number of allocated input streams */
alloc_instrms = op_strm_max_index_in ();
/* loop through each allocated stream */
for (i = 0; i <= alloc_intstrms; i++)
{
/* if an input stream is connected, and... */
if (op_strm_connected (OPC_STRM_IN, i) == OPC_TRUE)
{
/* if an input stream is connected, access a packet from the source module. */
op_strm_access (i);
/* Collect and forward the packet onto the bus, if one was obtained. */
if (op_strm_empty (i) == OPC_FALSE)
op_pk_send (op_pk_get (i), OUTSTRM_BUS);
}
}
Details
There are two primary techniques of accessing packets from a module which is connected to one of the input streams of a processor (or queue). The active technique (with respect to the source module) sends packets to the destination module automatically at synchronous or asynchronous times, using the op_pk_send…() series of KPs. This technique does not require any scheduling on the part of the destination module, since it will be automatically invoked by stream interrupts as the packets arrive. The passive technique (with respect to the source module) relies on the destination module to determine when it is free to process packets, and then interrupt the source module to obtain more packets to process. The interrupt type is usually forced, and is performed with an access interrupt created by this KP, but it can also be performed using a remote interrupt created by the KP op_intrpt_force_remote(). When the source module's process is invoked by the interrupt, it can determine the cause of the interrupt (using op_intrpt_strm()), and forward one or more packets to the destination using the KP op_pk_send_quiet(); the quiet mode is used to avoid scheduling an irrelevant interrupt for the destination module, since this module already is expecting a packet to be forwarded.
Purpose
Provides a mechanism for causing an access interrupt to occur at the module which is connected to the specified input stream. This capability is designed so that an active server processor can pull packets as required out of a queue running a passive queueing process (such as the base models pc_fifo and pc_lifo). However, the usefulness of this KP can be expanded to address any situation where a processor or queue wants to interrupt another processor or queue connected to one of its input streams.
Errors
- Recoverable Error: KP requires process context.
- Recoverable Error: No input streams exist at module.
- Recoverable Error: Input stream index (
<instrm_index>) is out-of-range. - Recoverable Error: Input stream index (
<instrm_index>) is unoccupied. - Recoverable Error: Source module does not support access interrupts.
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