op_pk_deliver_forced()
Abstract
Forwards the specified packet to a remote module, forces an immediate arrival at the module which causes an invocation of the corresponding process, and releases ownership of the packet by the invoking process.
Syntax
op_pk_deliver_forced (pkptr, mod_objid, instrm_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().] |
mod_objid |
Objid |
object ID of the remote module [An module object ID can be obtained from several KPs in the Topo and Id packages: op_id_self(), op_topo_child(), and op_id_from_name().] |
instrm_index |
int |
index of an input packet stream of the remote module |
Return Type
void
No return value.
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))
{
resp_pkptr = op_pk_get (0);
op_pk_fd_get (resp_pkptr, 0, &resp_code);
}
Details
This KP forwards the specified packet to the specified remote module without any delay or scheduling. The corresponding forced event is not scheduled, so the simulation event list is not involved in this operation. The forced event causes an immediate invocation of the remote module’s process with a stream interrupt. While the remote module process is responding to the stream interrupt, the invoking process is suspended; when the remote process enters an unforced state and releases control, this KP will return control to the invoking process, which will resume at the statement following the call to this KP.
If the remote module is a processor or a queue, its associated process can determine that the interrupt is due to an input stream via the KP op_intrpt_type(). Packets that arrive on input packet streams can be obtained by the remote process via the KP op_pk_get().
When a packet is passed to this KP, the invoking process loses ownership of the packet, because ownership is transferred to the remote module. Any KPs invoked by the delivering process that are passed the “stale” packet pointer will result in packet ownership errors.
Both unformatted and formatted packets can be transferred via this KP.
WARNING: Forced interrupts are inefficient and potentially dangerous in parallel simulations. To execute a forced interrupt, a particular thread of execution must set an execution lock on both current module and the module to which the forced interrupt is to be delivered. As a result, it is possible to run into a deadlock situation. For example, a deadlock will occur if thread 1 is executing an event for module A and attempts to issue a forced interrupt to module B at the same time that thread 2 is executing an event for module B and attempts to issue a forced interrupt to module A.
Purpose
Provides a mechanism to transfer packets between modules without relying on packet streams. Delivering packets using this KP is an alternative to the packet stream-oriented op_pk_send…() series of KPs. This KP is a variation of the basic op_pk_deliver() operation. op_pk_deliver_forced() is useful when the remote process must respond to the delivered packet before the delivering process can continue operations. Other variants of op_pk_deliver() provide delayed or quiet arrivals at the remote module. Packets may be delivered to other processes running in processors or queues, or to transmitter modules.
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>). - Recoverable Error: Object ID (
<mod_objid>) is out-of-range.
Reference
- Use the KP op_pk_deliver() to deliver a packet through the normal event-scheduling technique
- Use the KP op_pk_deliver_delayed() to deliver a packet with a delayed arrival
- Use the KP op_pk_deliver_quiet() to deliver a packet without causing an interrupt at the remote module
- Use the
op_pk_send…()KPs to forward packets to adjacent modules using packet streams - Use the KP op_pk_get() to obtain a pointer to an arriving packet