op_ev_cancel_if_pending()
Abstract
Revokes an event that has been previously scheduled, after first verifying that the event is pending.
Syntax
op_ev_cancel_if_pending (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 event was cancelled successfully; OPC_COMPCODE_FAILURE if the event was invalid or cannot be cancelled.
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_if_pending (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
This KP first verifies that the event referenced by evhandle is pending, then tries to cancel the event. The event is pending if it is not the current event, but is still scheduled. Even if the event is pending, cancellation might fail if another thread simultaneously grabs the event. If the event is cancelled and was a stream interrupt, the packet associated with the event is destroyed.
Purpose
Provides a mechanism for revoking events that are no longer necessary or desirable. This KP works like op_ev_cancel(), except that it also verifies that the event is pending before cancelling it. This KP is useful in multithreaded environments, where a modelling construct such as:
if (op_ev_valid (evh))
{
op_ev_cancel (evh);
}
might fail if event execution begins in another thread between the two function calls.
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() to cancel an event in a non-parallel environment.
- 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.