op_intrpt_schedule_process()
Abstract
Schedules a process interrupt for a particular process, at the specified time.
Syntax
op_intrpt_schedule_process (pro_handle, time, code)
| Argument | Type | Description |
|---|---|---|
pro_handle |
Prohandle |
handle for the process that is to receive an interrupt at the specified time. [A number of KPs in the Pro package can be used to obtain process handles, including op_pro_self(), op_pro_parent(), and op_pro_root().] |
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 |
Integer value that will be associated with the interrupt and be made available to the destination process via the KP op_intrpt_code(). This value has a user-defined interpretation and typically serves to distinguish between the various possible causes of a process interrupt in the modeled system. 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. |
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/x25); process model (x25_dce_chan); state (p6):
else
{
/* We came here normally because of a CLEAR REQUEST packet. */
/* Reset the channel. */
x25_dce_channel_reset ();
/* Send a confirmation packet to the DTE. */
x25_pk_send_local (chan_vars->data_link, chan_vars->number, x25_GFI_BASE,
X25C_PT_CLEAR_CONFIRM);
/* Send a CLEAR INDICATION to the remote end. */
x25_dce_pk_send_remote (OSIC_N_DISCONNECT_INDICATION, pkptr);
/* Notify our root process that we can be deleted. The deletion will take */
/* place after the current invocation of this process completes. */
op_intrpt_schedule_process (op_pro_parent (op_pro_self ()), op_sim_time(),
chan_vars->number);
}
Details
As with other event types that target particular processes (such as self interrupts), the execution of a process interrupt might occur after the destruction of the process in question. This will result in a diagnostic error at the scheduled interrupt time, and the interrupt will not be delivered. For such situations, it is recommended that—when possible—the event handle returned by op_intrpt_schedule_process() be used to cancel the event at the time when the destination process is destroyed.
It is possible to use this KP to schedule events for the current process, in a manner similar to the use of op_intrpt_schedule_self().
If a recoverable error occurs (see Errors section), this KP will return an event handle that is invalid. This condition can be tested for by calling the KP op_ev_valid().
It is sometimes necessary to cancel the process interrupt due to changing conditions, as mentioned above. 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;
/* process interrupt scheduling */
evh = op_intrpt_schedule_process (proch, 5.0, AL_CODE);
/* process interrupt cancelling */
op_ev_cancel (evh);
Purpose
Provides the ability to invoke a process in a deferred manner, in contrast to op_pro_invoke(), which allows process invocation but only in an immediate fashion. In addition, op_intrpt_schedule_process() supports invocation of processes outside the current module, which op_pro_invoke() does not.
Processes generally need to invoke each other when cooperating on a single task. An example might be the release of a resource or notification of a task completion; although remote interrupts also can support this type of activity, this KP provides the added ability to interrupt a particular process, as opposed to a module. This avoids interrupting other processes in the destination module and having them act as intermediaries.
Errors
- Program Abort: KP requires process context.
- Program Abort: Segmentation violation. (due to a malformed process handle).
- Recoverable Error: Process handle is invalid.
- Recoverable Error: Process handle is for destroyed process (
<proc_id>). - Recoverable Error: Specified time (
<time>) is less than current time. - Recoverable Error: Specified time (
<time>) is an invalid double value.
Reference
- Use the KP op_intrpt_schedule_self() to schedule a self interrupt
- Use the KP op_intrpt_schedule_remote() to schedule a remote interrupt
- Use the KP op_ev_cancel() to cancel a pending interrupt
- Use the KPs op_pro_parent(), op_pro_self(), and op_pro_root() to obtain process handles.