op_ev_next_local()
Abstract
Obtains the event handle referring to the next local event, that is, the next event expected to occur at the currently executing module (sequential simulations only).
Syntax
op_ev_next_local (evhandle)
| Argument | Type | Description |
|---|---|---|
evhandle |
Evhandle |
event handle that identifies the event [An event handle can be obtained from several KPs in this package—such as op_ev_current(), op_ev_seek_time(), and op_ev_next()—and others such as op_intrpt_schedule_self().]. |
Return Type
Evhandle
Event handle that represents the next event expected to occur at the currently executing module. If a recoverable error occurs, an invalid event handle is returned.
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
This KP returns the event handle referring to the next event that is scheduled to occur at the processor or queue that called this KP. For this reason the event handle that is passed to this KP must itself refer to an event for the currently executing processor or queue, or an error will occur.
See the Details section of the KP op_ev_next() for more information on the behavior when the specified event is forced. In all cases, this KP behaves exactly as op_ev_next(), except that it ignores events that are not local.
Purpose
Provides a mechanism to step through each future local event in order.
Note: This KP works only in a sequential simulation context. In a parallel simulation, where events in the current time cell might be executed in varying fashion based on what the threads are doing, it will act as if there are no events after the current one.
Errors
- Program Abort: KP requires process context.
- 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: Event handle refers to an event that is not local.
Reference
- Use the KP op_ev_current() to obtain the current event’s Evhandle
- Use the KP op_ev_next() to obtain the succeeding events’ Evhandles