op_intrpt_schedule_remote()
Abstract
Schedules a remote interrupt for the specified processor or queue, at the specified time.
Syntax
op_intrpt_schedule_remote (time, code, mod_objid)
| Argument | Type | Description |
|---|---|---|
time |
double |
scheduled time for the interrupt [This value is an absolute simulation time, rather than a delay relative to the current simulation time. If the “sim_time_quantum“ preference has a value other than 0.0, time will be truncated internally to a multiple of the specified quantum.] |
code |
int |
user-defined numeric code for association with the interrupt [This value is an arbitrary, user-defined integer which can be used as an identification code for the scheduled interrupt; the code can be obtained when the interrupt invokes the process, using the KP op_intrpt_code(). You can assign a text string that will be printed along with this code when it appears in ODB event banners and traces. See “Interrupt Code Map“ on page 507 for details.] |
mod_objid |
Objid |
object ID of the processor or queue which will receive the interrupt [A processor or queue object ID can be obtained from several KPs in the Id package: op_id_self(), op_topo_child(), and op_id_from_name().] |
Return Type
Evhandle
Event handle for the scheduled interrupt.
[This returned value can be stored in a state variable for possible later use to identify the interrupt in an invocation of op_ev_cancel().]
Example
Excerpt from: example model (models/std/fddi); process model (fddi_mac); function block.
fddi_tk_inject (int address)
{
/* Re-insert the token into the ring in response to */
/* a station registering its intent to send data after */
/* a dead period on the ring. */
FIN (fddi_tk_inject (address))
/* The token is recreated and reinserted onto the ring */
/* at the specified station which is not necessarily the */
/* station now requesting the token. */
/* The station which will reinsert the token is */
/* asked to do so by means of a remote interrupt. */
op_intrpt_schedule_remote (op_sim_time (), 0, Fddi_Address_Table [address]);
FOUT
}
Details
Invoking this KP places a new event on the simulation event list; this new event represents a remote interrupt that is scheduled to be delivered at the specified time. As soon as the event is scheduled, this KP returns control to the invoking process, which is then free to pursue any activities. The event will take place at the scheduled simulation time, but not before the execution of other higher priority events scheduled for that specific simulation time. When all earlier events have been executed, and the remote interrupt event is at the head of the simulation event list, its simulation time is established as the current simulation time and the event is executed. The execution of the event causes a remote interrupt to be delivered to the specified module. The module’s process can obtain the specified code associated with the interrupt via the KP op_intrpt_code().
It is sometimes necessary to cancel the remote interrupt due to changing conditions (for example, if a process schedules an interrupt requesting a routing update for a particular time, but then receives an update due to another reason before the scheduled update request is delivered to the remote module). Cancelling an interrupt requires that the event handle returned by this KP be stored in a state variable, to be later passed to the KP op_ev_cancel(), as shown in the following examples:
/* state variable declaration */
Evhandle \evh;
/* remote interrupt scheduling */
evh = op_intrpt_schedule_remote (stime, 22, mod_objid);
/* remote interrupt cancelling */
op_ev_cancel (evh);
Purpose
Provides a mechanism for remotely invoking one process from another, without requiring a physical packet stream or statistic wire connection between them. This is useful when one process needs to alert another process that something of interest has occurred (for instance, a queue process can interrupt a processor in another node when it has saturated its packet capacity).
WARNING: Remote interrupts must be delivered only to processors and queues; otherwise an error will occur.
Errors
- Program Abort: Allocation of memory failed.
- Recoverable Error: Specified time (
<time>) is less than current time. - Recoverable Error: Specified time (
<time>) is an invalid double value. - Recoverable Error: Object ID (
<mod_objid>) is out-of-range. - Recoverable Error: Object (
<mod_objid>) has incorrect type; queue or processor objects are expected.
Reference
- Use the KP op_intrpt_schedule_self() to schedule a self interrupt
- Use the KP op_intrpt_force_remote() to force a remote interrupt
- Use the KP op_intrpt_schedule_call() to schedule a procedure interrupt
- Use the KP op_ev_cancel() to cancel a pending interrupt
- Use the KP op_intrpt_code() to obtain the code associated with an incoming interrupt