op_ev_cancel()
Abstract
Revokes an event that has been previously scheduled.
Syntax
op_ev_cancel (evhandle)
| Argument | Type | Description |
|---|---|---|
evhandle |
Evhandle |
event handle that identifies the event to be canceled An event handle can be obtained from several KPs in this package, such as op_ev_seek_time() and op_ev_next() and others such as op_intrpt_schedule_self(). |
Return Type
Compcode
OPC_COMPCODE_SUCCESS if the operation completed successfully; OPC_COMPCODE_FAILURE otherwise.
Example
/* Obtain the currently executing event (it must be at this module, */
/* since this module woke up.) and the one after it. */
this_event = op_ev_current ();
next_event = op_ev_next_local (this_event);
/* Loop through all of the events scheduled for this module */
/* and cancel any that are retransmission timers. */
while (op_ev_valid (next_event))
{
if ((op_ev_type (next_event) == OPC_INTRPT_SELF) &&
(op_ev_code (next_event) == RETRANS_TIMER))
{
retrans_timer = next_event;
next_event = op_ev_next_local (retrans_timer);
op_ev_cancel (retrans_timer);
}
else
/* Obtain the next event; if there are no more events, op_ev_next_local () */
/* will return an invalid event handle and the loop will terminate. */
next_event = op_ev_next_local (next_event);
}
Details
Canceling an event removes it from the simulation event list and prevents its delivery to the destination module. Applying this KP to events that have already been delivered or are currently executing will cause an error. Only pending events are allowed to be canceled.
This procedure can be used to cancel events without compromising efficiency because the Simulation Kernel caches information about events in their corresponding event handles to allow them to be located quickly without having to search through the event scheduling data structures. Using op_ev_cancel() to cancel events before they are delivered is more efficient than allowing events to be delivered to their destination and then ignoring them.
Purpose
Provides a mechanism for revoking events that are no longer necessary or desirable. A common use of this KP involves the annulment of time-outs that are represented by interrupts scheduled via op_intrpt_schedule_self(). If an acknowledgment packet arrival or some other interrupt occurs before a time-out interval expires, the time-out is typically canceled via this KP and possibly reset to its original duration through rescheduling.
Errors
- Program Abort: Segmentation violation. (due to a malformed event handle)
- Recoverable Error: Event handle refers to an event that is either invalid or not currently scheduled.
- Recoverable Error: Current event (
<schedule_id>) cannot be canceled. - Recoverable Error: Event in progress (
<schedule_id>) cannot be canceled. - Recoverable Error: Cannot cancel unlocated event (
<schedule_id>).
Reference
- Use the KP op_ev_cancel_if_pending() to cancel an event after first verifying that the event exists.
- Use the KP op_ev_pending() to determine if an event is cancellable.
- Use the KP op_intrpt_schedule_self() to schedule a self interrupt for a process.
- Use the KP op_intrpt_clear_self() to revoke all pending interrupts for a process.