op_pk_deliver_delayed()
Abstract
Forwards the specified packet to a remote module, schedules the packet’s arrival at the module for a delayed simulation time, and releases ownership of the packet by the invoking process.
Syntax
op_pk_deliver_delayed (pkptr, mod_objid, instrm_index, delay)
| 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 |
delay |
double |
amount of simulation time to delay arrival of packet [This must be a positive number (or zero).] |
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 */
length = (int) op_dist_uniform (MAX_PK_SIZE);
pkptr = op_pk_create (length);
/* stuff packet with operation code */
op_pk_fd_set (pkptr, 0, OPC_FIELD_TYPE_INTEGER, OPCODE_DOWNLOAD, 16);
/* deliver the packet to remote processor with a delay */
com_delay = length / 300.0;
op_pk_deliver_delayed (pkptr, proc_objid, 0, com_delay);
Details
This KP schedules the specified packet’s arrival at the specified remote module. The arrival is scheduled for the current simulation time plus the specified delay, and the corresponding event is added to the simulation event list. As soon as the event is scheduled, this KP returns control to the invoking process. The event will take place at the delayed simulation time, but not before the execution of other events already scheduled for that specific simulation time. During the delay interval, the invoking process is free to pursue any activities; it no longer has any association with the delayed packet. Thus this KP can be used to model the processing delays of a multiprocessing server; uniprocessing scenarios will probably have to restrict further processing of packets during the delay interval using a self-scheduled interrupt. Upon execution of the scheduled event, the remote module will be invoked with a stream interrupt. 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 destination process via the KP op_pk_get().
Once a packet is passed to this KP, the invoking process loses ownership of the packet, since the 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.
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 that is useful for modeling a processing or transmission delay due to the invoking process. Other variants of op_pk_deliver() provide forced or quiet arrivals at the remote module. Packets can 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: Delay value (
<delay>) is out-of-range. - Recoverable Error: Object ID (
<mod_objid>) is out-of-range.
Reference
- Use the KP op_pk_deliver() to deliver a packet without any delay
- Use the KP op_pk_deliver_forced() to deliver a packet for immediate processing at a remote module
- 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