Package Overview
The Event package is a collection of Kernel Procedures that provide a process with information about events in the simulation. These events can be thought of as being stored in a list in order of execution. The head of the event list is the current event and each event in the list will occur before the following one. The Event package uses Evhandles to refer to events.
Several KPs provide access to the events in the event list. The KP op_ev_current() returns the Evhandle associated with the current event, and op_ev_current_execid() returns the execution ID of the current event. With any valid event as a starting point, a process can step through the event list using the KP op_ev_next(). If the process is searching for an event relative to some simulation time value, the KP op_ev_seek_time() will locate the event that is closest to the time of interest.
The KPs described above apply to the entire event list. A similar set of KPs operate on local events. An event is considered local if it is scheduled to occur at the module that calls the KP. Since the current event woke up the invoking process, it must be local. Thus, op_ev_current() can be thought of as a local event KP. op_ev_next_local() provides the capability to step through local events.
The Event package can be used to monitor future events or to find a particular set of events. If a process needs to loop through the entire set of events, it can call op_ev_count(), which returns the number of events, and can then use the count as a for loop upper bound. op_ev_count_local() returns the number of local events.
Events that have been scheduled sometimes become obsolete before they arrive. For instance, a process may schedule a time-out interval for five minutes, only to be interrupted two minutes later by an arriving acknowledgment packet. Since the time-out has become unnecessary, the possible arrival of the pending event is an inconvenience which would require special handling by the process model. The KP op_ev_cancel() eliminates the need to specially handle events that have lost significance. This KP cancels a pending event, based on its Evhandle. The KP op_ev_pending() determines whether an event is still pending. If op_ev_cancel() is applied to an event that is not pending, a recoverable error will occur. The KP op_ev_cancel_if_pending() can be used in multithreaded environments to verify the event before cancelling it.
Two commonly used attributes of an event are its type and scheduled time. The KP op_ev_type() provides the process with an integer code that represents the type of the event; this code can be compared with those in Table 59 “Interrupt Type Symbolic Constants“ on page 15. The KP op_ev_time() returns the time when the event is scheduled to occur.
Self, remote or multicast interrupts can have many different purposes. For instance, a single process may schedule self interrupts for modeling various kinds of processing delays and time-out intervals. In order to distinguish the purpose of such interrupts, an integer numeric code with a user-defined interpretation can be associated with self, remote and multicast interrupts. The code of the corresponding event is available from the KP op_ev_code().
Stream interrupts are caused by packets arriving on input streams. The KP op_ev_strm() determines the input stream on which the packet will arrive.
Statistic interrupts are caused by triggers responding to specific types of changes in the values of module statistics. The KP op_ev_stat() determines which input statistic is associated with an event. Note that this KP does not provide information about the statistic (such as its name or the triggering condition); it only provides the numeric index of the input statistic.
To obtain the ID of a specific event, use op_ev_id(). To obtain a string representation of the event ID, use op_ev_id_str_get().
Most types of events originate at a specific module. Stream interrupts originate at the module that generated or forwarded an arriving packet. Self, remote and multicast interrupts originate at the modules that schedule them. To obtain the object ID of the module (or link or node in the case of failure and recovery interrupts) that is the source of an event, the KP op_ev_src_id() can be used. Three types of events do not have source objects: begin simulation, end simulation, and regular interrupts. In order to obtain the object ID of the module that is the destination of an event, the KP op_ev_dst_id() can be used.
The KP op_ev_equal() provides the capability to compare two Evhandles. If the Evhandles refer to the same event, then they are considered equal. This is useful for a process that is waiting for a particular event. It can store the Evhandle of that event and compare it to the current event using op_ev_equal().
Events are either scheduled or forced. If an event is placed in the event list in such a manner as to be executed in order, then it is a scheduled event. A forced event by-passes the event list and immediately interrupts the destination module, “forcing” it to handle the event.
Events that originate at processes can have user-specified information associated with them. This information can convey data about an event and possibly about the type of service requested. There are two ways to associate such information with an event:
- Interface Control Information (ICI)—ICIs are manipulated by Ici Package KPs, both in the originating process and the receiving process. The KP op_ici_install() binds a specified ICI with outgoing interrupts at the originating process. The KP op_ev_ici() obtains an ICI associated with an event.
- State information—State information provides a faster way of conveying data about an event than the ICI mechanism. The KP op_ev_state_install() specifies a user-defined data structure to be associated with events. The KP op_ev_state() returns the state associated with an event. The KP op_ev_state_clear() will remove the state associated with an event.
Event handles are often tested for validity by Event package KPs that accept them as arguments. Event handles become invalid when they refer to events that have been canceled or have already occurred; also event handles may be the result of a KP that returns an event handle indicating an error. The KP op_ev_valid() can be used to test the validity of an event handle. This typically is necessary when an event handle is returned from a KP and there is some doubt as to whether the KP has succeeded; similarly if it is not certain that an event handle refers to an event that is still pending, op_ev_valid() may be called before any other KPs are used to operate on the event handle.