Package ikr.simlib.events.calendar

Calendars

See: Description

Class Summary

Class	Description
Calendar	Calendars are special event handlers derived from the abstract base class Calendar.

Package ikr.simlib.events.calendar Description

Calendars

All calendars, e.g. SimpleCalendar, are derived from the abstract base class Calendar.

The form in which the events are stored in the calendar, after being registered in the calendar and waiting for their execution, must be defined in derived classes. The library offers two special calendars:
- StdCalendar uses a linear list for storing the events. For a high number of events within the calendar this implementation gets slow. Therefore this class is only recommended for models with few events or for test purposes.
- In SimpleCalendar a relatively complex but efficient procedure, especially for large numbers of waiting events, is used to store event information.

Generally, a system has a central calendar.

Event Handling Procedures

Posting Events
The following steps are necessary if a function of a model component is to register an event:
- The postEvent() method must be called with a reference to the event (Event or one of its derived classes), which generally is a data element of the model component (see ikr.simlib.model) , and the time at which the event is expected to occur as parameters. Optionally, a priority may be passed on. It is an integer and controls the order in which events are processed, which are posted for the same time. Larger values are more important and cause events to be executed primarily.

Cancelling Events
If it should happen that an existing event is no longer valid, because another event has already occurred, then the event will be removed from the event list of the calendar.
- The cancelEvent() method is called with a reference to the event as a parameter which will cause the removal of the event.
- Furthermore, the calendar calls the cancelEvent() method on the event to be removed.
- The event time is passed along with these methods.

Processing Events
When processing events, the simulation library offers the user many degrees of freedom. In the typical case of a central calendar of the type Calendar, or one of its derived classes, the following actions will occur:
- The sequence control (class derived from Simulation, ikr.simlib.control) will call the function processPendingEvents().
- processPendingEvents() contains a loop, in which events can be successively processed. This loop can be indirectly stopped by sequence control.
- Within the loop the function getNextEvent() from the class Calendar is called first, which will remove the currently next event in the event list and return a pointer.
- After that the event is processed by calling the Event method processEvent() (see Event). Normally the responsibility is passed on to the responsible model component.

Posting Events Multiple Times
Events may be posted multiple times as long as they do not use embedded events. A particular post of an event may can be identified by its time for which it is posted. When specifying a time with cancelEvent(), a particular post may be cancelled.

Associating a Context with a Posted Event
Often, it is useful to associate a context with an event, that has been posted to a particular time in the calendar. For example, the InfiniteServer associates a message with each event posting in order to forward the respective message on the output port when the event is processed. The easiest way to implement this is by deriving a new class from Event. For example see the class InfiniteServerEvent.