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

本站文档由 北京智网畅联科技有限公司 整理、翻译并提供 · 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