umontreal.iro.lecuyer.simevents

Class Event

java.lang.Object

umontreal.iro.lecuyer.simevents.Event

All Implemented Interfaces:

java.lang.Comparable<Event>

public abstract class Event
extends java.lang.Object
implements java.lang.Comparable<Event>

This abstract class provides event scheduling tools. Each type of event should be defined as a subclass of the class Event, and should provide an implementation of the method actions which is executed when an event of this type occurs. The instances of these subclasses are the actual events.

Each event is linked to a simulator represented by an instance of Simulator before it can be scheduled and processed. A default simulator, given by Simulator.getDefaultSimulator, is used if no simulator is linked explicitly with an event. When an event is constructed, it is not scheduled. It must be scheduled separately by calling one of the scheduling methods schedule, scheduleNext, scheduleBefore, etc. An event can also be cancelled before it occurs.

A scheduled event has an associated time at which it will happen and a priority, which can be queried using the methods time and priority, respectively. By default, events occur in ascending order of time, and have priority 1. Events with the same time occur in ascending order of priority. For example, if events e1 and e2 occur at the same time with priority 2 and 1 respectively, then e2 will occur before e1. Events with the same time and priority occur in the order they were scheduled.

Constructor Summary

Constructors

Constructor and Description
Event() Constructs a new event instance, which can be placed afterwards into the event list of the default simulator.
Event(Simulator sim) Construct a new event instance associated with the given simulator.

Method Summary

Methods

Modifier and Type	Method and Description
abstract void	actions() This is the method that is executed when this event occurs.
boolean	cancel() Cancels this event before it occurs.
boolean	cancel(java.lang.String type) Finds the first occurence of an event of class ``type'' in the event list, and cancels it.
int	compareTo(Event e) Compares this object with the specified object e for order.
double	priority() Returns the priority of this event.
void	reschedule(double delay) Cancels this event and reschedules it to happen in delay time units.
void	schedule(double delay) Schedules this event to happen in delay time units, i.e., at time sim.time() + delay, by inserting it in the event list.
void	scheduleAfter(Event other) Schedules this event to happen just after, and at the same time, as the event other.
void	scheduleBefore(Event other) Schedules this event to happen just before, and at the same time, as the event other.
void	scheduleNext() Schedules this event as the first event in the event list, to be executed at the current time (as the next event).
void	setPriority(double priority) Sets the priority of this event to inPriority.
void	setSimulator(Simulator sim) Sets the simulator associated with this event to sim.
void	setTime(double time) Sets the (planned) time of occurence of this event to time.
Simulator	simulator() Returns the simulator linked to this event.
double	time() Returns the (planned) time of occurence of this event.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Event

public Event()

Constructs a new event instance, which can be placed afterwards into the event list of the default simulator. For example, if Bang is an Event subclass, the statement ``new Bang().scheduleNext();'' creates a new Bang event and places it at the beginning of the event list.

Event

public Event(Simulator sim)

Construct a new event instance associated with the given simulator.

Parameters:

sim - Instance of class Simulator associated with the new Event

Method Detail

schedule

public void schedule(double delay)

Schedules this event to happen in delay time units, i.e., at time sim.time() + delay, by inserting it in the event list. When two or more events are scheduled to happen at the same time and with the same priority, they are placed in the event list (and executed) in the same order as they have been scheduled. Note that the priority of this event should be adjusted using setPriority before it is scheduled.

Parameters:

delay - simulation time that must pass before the event happens

scheduleNext

public void scheduleNext()

Schedules this event as the first event in the event list, to be executed at the current time (as the next event).

scheduleBefore

public void scheduleBefore(Event other)

Schedules this event to happen just before, and at the same time, as the event other. For example, if Bing and Bang are Event subclasses, after the statements

Bang bigOne = new Bang().schedule(12.0);
new Bing().scheduleBefore(bigOne);

the event list contains two new events scheduled to happen in 12 units of time: a Bing event, followed by a Bang called bigOne.

Parameters:

other - event before which this event will be scheduled

scheduleAfter

public void scheduleAfter(Event other)

Schedules this event to happen just after, and at the same time, as the event other.

Parameters:

other - event after which this event will be scheduled

reschedule

public void reschedule(double delay)

Cancels this event and reschedules it to happen in delay time units.

Parameters:

delay - simulation time units that must elapse before the event happens

cancel

public boolean cancel()

Cancels this event before it occurs. Returns true if cancellation succeeds (this event was found in the event list), false otherwise.

Returns:

true if the event could be cancelled

cancel

public final boolean cancel(java.lang.String type)

Finds the first occurence of an event of class ``type'' in the event list, and cancels it. Returns true if cancellation succeeds, false otherwise.

Parameters:

type - name of an event subclass

Returns:

true if an event of this class was found and cancelled

simulator

public final Simulator simulator()

Returns the simulator linked to this event.

Returns:

the simulator linked to the event

setSimulator

public final void setSimulator(Simulator sim)

Sets the simulator associated with this event to sim. This method should not be called while this event is in an event list.

Parameters:

sim - the Simulator

time

public final double time()

Returns the (planned) time of occurence of this event.

Returns:

the time of occurence of the event

setTime

public final void setTime(double time)

Sets the (planned) time of occurence of this event to time. This method should never be called after the event was scheduled, otherwise the events would not execute in ascending time order anymore.

Parameters:

time - new time of occurence for the event

priority

public final double priority()

Returns the priority of this event.

Returns:

the priority of the event

setPriority

public final void setPriority(double priority)

Sets the priority of this event to inPriority. This method should never be called after the event was scheduled, otherwise the events would not execute in ascending priority order anymore.

Parameters:

priority - new priority for the event

compareTo

public int compareTo(Event e)

Compares this object with the specified object e for order. Returns -1 or +1 as this event occurs before or after the specified event e, respectively. If the two events occur at the same time, then returns -1, 0, or +1 as this event has a smaller, equal, or larger priority than event e.

Specified by:

compareTo in interface java.lang.Comparable<Event>

actions

public abstract void actions()

This is the method that is executed when this event occurs. Every subclass of Event that is to be instantiated must provide an implementation of this method.