op_pk_send_quiet()
Abstract
Forwards the specified packet through an output packet stream (does not schedule an interrupt or invoke the process running at the destination module), then releases ownership of the packet.
Syntax
op_pk_send_quiet (pkptr, outstrm_index)
| 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().] |
outstrm_index |
int |
index of an output packet stream of the surrounding module |
Return Type
void
No return value.
Example
Excerpt from: example model (models/std/base); process model (pc_lifo); state (SEND_HEAD); enter execs.
/* a request has been made to access the queue */
/* check if its empty */
if (!op_subq_empty (0))
{
/* access the first packet in the subqueue */
pkptr = op_subq_pk_remove (0, OPC_QPOS_HEAD);
/* forward it to the destination */
/* without causing a stream interrupt */
op_pk_send_quiet (pkptr, 0);
}
Details
This KP forwards the specified packet to the destination module without any delay or scheduling. The packet arrival is not scheduled, so the simulation event list is not involved in this operation. No interrupt is delivered to the destination module due to the packet arrival, hence the term "quiet". The destination module process is thus responsible for detecting the forwarded packet's presence in an input stream at some time in the future when it is invoked by another interrupt. Multiple packets can be sent to the same destination module during a single process invocation, since the destination module input stream will buffer incoming packets. When the destination process is next invoked, it can detect packets which have quietly arrived in its input streams using op_strm_empty() or op_strm_pksize(). If packets are present in the streams, they can be obtained using op_pk_get().
Once a packet is passed to this KP, the invoking process loses ownership of the packet. Ownership is transferred to the destination module. Any KPs invoked by the sending process which are passed the "stale" packet pointer will result in packet ownership errors.
This KP requires a process context, so it must only be invoked from a process model, or a function that has been directly or indirectly invoked by a process model. Both unformatted and formatted packets can be transferred via this KP.
Purpose
Provides a mechanism to transfer packets within a single node between modules connected by packet streams. This KP is a variation of op_pk_send() and is useful when the destination module must not be interrupted by the packet's arrival, typically because it is already expecting to receive a packet after having used the KP op_strm_access(). Other variants of op_pk_send() provide forced or delayed arrivals at the destination module, and the alternative op_pk_deliver…() KPs provide transport of packets without requiring the presence of a physical stream object.
op_pk_send_quiet() allows packets to be forwarded to other processes running in processors or queues, or to transmitter modules that provide an interface to communication links between nodes.
Errors
- Program Abort: Segmentation violation.(due to an invalid packet pointer or malformed 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>). - Program Abort: Packet delivery failed at object (
<mod_objid>), stream (<instrm_index>). - Program Abort: KP requires process context.
- Recoverable Error: Output stream index (
<outstrm_index>) is out-of-range. - Recoverable Error: Output stream index (
<outstrm_index>) is unoccupied.
Reference
- use op_pk_send() to send a packet through the normal event-scheduling technique
- use op_pk_send_delayed() to send a packet with a delayed arrival
- use op_pk_send_forced() to send a packet and immediately begin processing at the destination
- use
op_pk_deliver…()to forward packets to modules without using packet streams - use op_strm_empty() or op_strm_pksize() to detect if an input stream contains packets
- use op_pk_get() to obtain a pointer to an arriving packet