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

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · Documentation compiled and provided by Beijing ZNetLink Technology Co., Ltd.

交流群 · QQ Group:OPNET/智网妙算网络仿真交流群(群号 486383494)

原文档 © 2017 Riverbed Technology · 本站为公益翻译,由 AI 辅助完成,请仔细甄别

Original documentation © 2017 Riverbed Technology. Community translation, AI-assisted. Contact: jiazequn@znetlink.com