sim.engine
Class Schedule

java.lang.Object
  extended bysim.engine.Schedule
All Implemented Interfaces:
java.io.Serializable

public class Schedule
extends java.lang.Object
implements java.io.Serializable

Schedule defines a threadsafe scheduling queue in which events can be scheduled to occur at future time. The time of the most recent event which has already occured is given by the time() method. If the current time is BEFORE_SIMULATION (defined to be EPOCH - 1), then the schedule is set to the "time before time" (the schedule hasn't started running yet). If the current time is AFTER_SIMULATION (positive infinity), then the schedule has run out of time. EPOCH (0.0) is defined as the first timestep for which you can legally schedule a value. EPOCH_PLUS_ESPILON is defined as the smallest possible second timestep for which you can legally sechedule a value. If you're scheduling events to occur on integer timesteps, you may want to ensure that your simulation does not run beyond MAXIMUM_INTEGER (9007199254740992L or 9.007199254740992E15). For values of a double d >= MAXIMUM_INTEGER, d + 1 == d !

An event is defined as a Steppable object. You can schedule events to either occur a single time or to occur repeatedly at some interval. If the event occurs repeatedly, the schedule will provide you with a Stoppable object on which you can call stop() to cancel all future repeats of the event. If instead you wish to "stop" a single-time event from occuring before its time has come, you should do so through the use of a TentativeStep object. At present you cannot delete objects from the Schedule -- just stop them and let them drop out in due course.

The schedule is pulsed by calling its step(...) method. Each pulse, the schedule finds the minimum time at which events are scheduled, moves ahead to that time, and then calls all the events scheduled at that time. Multiple events may be scheduled for the same time. No event may be scheduled for a time earlier than time(). If at time time() you schedule a new event for time time(), then actually this event will occur at time time()+epsilon, that is, the smallest possible slice of time greater than time().

Events at a step are further subdivided and scheduled according to their ordering, an integer. Objects for scheduled for lower orderings for a given time will be executed before objects with higher orderings for the same time. If objects are scheduled for the same time and have the same ordering value, their execution will be randomly ordered with respect to one another.

Previous versions of Schedule required you to specify the number of orderings when instantiating a Schedule. This is no longer the case. The constructor is still there, but the number of orderings passed in is entirely ignored.

You might be wondering: why bother with using orderings? After all, can't you achieve the same thing by just stretching elements out in time? There are two reasons to use orderings. First, it allows you to use the time() method to keep tabs on the current time in a way that might be convenient to you. But second and more importantly, MASON's GUI facility will update its displays and inspectors only after all Steppables scheduled for a given timestamp have completed, and so orderings give you a way of subdividing the interval of time between GUI updates.

You can clear out the entire Schedule by calling reset(), including about-to-be executed Steppables in the current timestep. However, this does not prevent AsynchronousSteppables from suddenly rescheduling themselves in the queue. Stopping the simulation from within a Steppable object's step() method is best done by calling SimState.kill(). From the main thread, the most straightforward way to stop a simulation is to just stop calling schedule.step(...), and proceed directly to SimState.finish().

You can get the number of times that step(...) has been called on the schedule by calling the getSteps() method. This value is incremented just as the Schedule exits its step(...) method and only if the method returned true. Additionally, you can get a string version of the current time with the getTimestamp(...) method.

Exception Handling. It's a common error to schedule a null event, or one with an invalid ordering or time. Schedule previously returned false or null in such situations, but this leaves the burden on the programmer to check, and programmers are forgetful! We have changed Schedule to throw exceptions by default instead. You can change Schedule back to returning false or null (perhaps if you want to handle the situations yourself more efficiently than catching an exception, or if you know what you're doing schedule-wise) by setting setThrowingScheduleExceptions(false).

See Also:
Serialized Form

Field Summary
static double AFTER_SIMULATION
           
static double BEFORE_SIMULATION
           
static double EPOCH
           
static double EPOCH_PLUS_EPSILON
           
static double MAXIMUM_INTEGER
           
 
Constructor Summary
Schedule()
          Creates a Schedule.
Schedule(int numOrders)
          Creates a Schedule.
 
Method Summary
 long getSteps()
           
 java.lang.String getTimestamp(double time, java.lang.String beforeSimulationString, java.lang.String afterSimulationString)
          Returns a given time in string format.
 java.lang.String getTimestamp(java.lang.String beforeSimulationString, java.lang.String afterSimulationString)
          Returns the current time in string format.
 boolean isThrowingScheduleExceptions()
           
 void reset()
          Empties out the schedule and resets it to a pristine state BEFORE_SIMULATION, with steps = 0.
 boolean scheduleComplete()
          Returns true if the schedule has nothing left to do.
 boolean scheduleOnce(double time, int ordering, Steppable event)
          Schedules the event to occur at the provided time, and in the ordering provided.
 boolean scheduleOnce(double time, Steppable event)
          Schedules the event to occur at the provided time, 0 ordering.
 boolean scheduleOnce(Steppable event)
          Schedules the event to occur at time() + 1.0, 0 ordering.
 boolean scheduleOnce(Steppable event, int ordering)
          Schedules the event to occur at time() + 1.0, 0 ordering.
 Stoppable scheduleRepeating(double time, int ordering, Steppable event)
          Schedules the event to recur at an interval of 1.0 starting at the provided time, and in the ordering provided.
 Stoppable scheduleRepeating(double time, int ordering, Steppable event, double interval)
          Schedules the event to recur at the specified interval starting at the provided time, and in the ordering provided.
 Stoppable scheduleRepeating(double time, Steppable event)
          Schedules the event to recur at the specified interval starting at the provided time, and at 0 ordering.
 Stoppable scheduleRepeating(double time, Steppable event, double interval)
          Schedules the event to recur at the specified interval starting at the provided time, in ordering 0.
 Stoppable scheduleRepeating(Steppable event)
          Schedules the event to recur at an interval of 1.0 starting at time() + 1.0, and at 0 ordering.
 Stoppable scheduleRepeating(Steppable event, double interval)
          Schedules the event to recur at the specified interval starting at time() + interval, and at 0 ordering.
 Stoppable scheduleRepeating(Steppable event, int ordering, double interval)
          Schedules the event to recur at the specified interval starting at time() + interval, and at the provided ordering.
 void setThrowingScheduleExceptions(boolean val)
           
 boolean step(SimState state)
          Steps the schedule, gathering and ordering all the items to step on the next time step (skipping blank time steps), and then stepping all of them in the decided order.
 double time()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EPOCH

public static final double EPOCH
See Also:
Constant Field Values

BEFORE_SIMULATION

public static final double BEFORE_SIMULATION
See Also:
Constant Field Values

AFTER_SIMULATION

public static final double AFTER_SIMULATION
See Also:
Constant Field Values

EPOCH_PLUS_EPSILON

public static final double EPOCH_PLUS_EPSILON

MAXIMUM_INTEGER

public static final double MAXIMUM_INTEGER
See Also:
Constant Field Values
Constructor Detail

Schedule

public Schedule(int numOrders)
Creates a Schedule. The numOrders argument is ignored.


Schedule

public Schedule()
Creates a Schedule.

Method Detail

setThrowingScheduleExceptions

public void setThrowingScheduleExceptions(boolean val)

isThrowingScheduleExceptions

public boolean isThrowingScheduleExceptions()

time

public double time()

getTimestamp

public java.lang.String getTimestamp(java.lang.String beforeSimulationString,
                                     java.lang.String afterSimulationString)
Returns the current time in string format. If the time is BEFORE_SIMULATION, then beforeSimulationString is returned. If the time is AFTER_SIMULATION, then afterSimulationString is returned. Otherwise a numerical representation of the time is returned.


getTimestamp

public java.lang.String getTimestamp(double time,
                                     java.lang.String beforeSimulationString,
                                     java.lang.String afterSimulationString)
Returns a given time in string format. If the time is BEFORE_SIMULATION, then beforeSimulationString is returned. If the time is AFTER_SIMULATION, then afterSimulationString is returned. Otherwise a numerical representation of the time is returned.


getSteps

public long getSteps()

reset

public void reset()
Empties out the schedule and resets it to a pristine state BEFORE_SIMULATION, with steps = 0. If you're looking for a way to kill your simulation from a Steppable, use SimState.kill() instead.


scheduleComplete

public boolean scheduleComplete()
Returns true if the schedule has nothing left to do.


step

public boolean step(SimState state)
Steps the schedule, gathering and ordering all the items to step on the next time step (skipping blank time steps), and then stepping all of them in the decided order. Returns FALSE if nothing was stepped -- the schedule is exhausted or time has run out.


scheduleOnce

public boolean scheduleOnce(Steppable event)
Schedules the event to occur at time() + 1.0, 0 ordering. If this is a valid time and event, schedules the event and returns TRUE, else returns FALSE.


scheduleOnce

public boolean scheduleOnce(Steppable event,
                            int ordering)
Schedules the event to occur at time() + 1.0, 0 ordering. If this is a valid time and event, schedules the event and returns TRUE, else returns FALSE.


scheduleOnce

public boolean scheduleOnce(double time,
                            Steppable event)
Schedules the event to occur at the provided time, 0 ordering. If the time() == the provided time, then the event is instead scheduled to occur at time() + epsilon (the minimum possible next timestamp). If this is a valid time and event, schedules the event and returns TRUE, else returns FALSE.


scheduleOnce

public boolean scheduleOnce(double time,
                            int ordering,
                            Steppable event)
Schedules the event to occur at the provided time, and in the ordering provided. If the time() == the provided time, then the event is instead scheduled to occur at time() + epsilon (the minimum possible next timestamp). If this is a valid time, ordering, and event, schedules the event and returns TRUE, else returns FALSE.


scheduleRepeating

public Stoppable scheduleRepeating(Steppable event)
Schedules the event to recur at an interval of 1.0 starting at time() + 1.0, and at 0 ordering. If this is a valid event, schedules the event and returns a Stoppable, else returns null. The recurrence will continue until time() >= AFTER_SIMULATION, the Schedule is cleared out, or the Stoppable's stop() method is called, whichever happens first.

Note that calling stop() on the Stoppable will not only stop the repeating, but will also make the Schedule completely forget (lose the pointer to) the Steppable scheduled here. This is particularly useful if you need to make the Schedule NOT serialize certain Steppable objects. Do not use this with a real-valued schedule.


scheduleRepeating

public Stoppable scheduleRepeating(Steppable event,
                                   double interval)
Schedules the event to recur at the specified interval starting at time() + interval, and at 0 ordering. If this is a valid interval (must be positive) and event, schedules the event and returns a Stoppable, else returns null. The recurrence will continue until time() >= AFTER_SIMULATION, the Schedule is cleared out, or the Stoppable's stop() method is called, whichever happens first.

Note that calling stop() on the Stoppable will not only stop the repeating, but will also make the Schedule completely forget (lose the pointer to) the Steppable scheduled here. This is particularly useful if you need to make the Schedule NOT serialize certain Steppable objects. Do not use this with a real-valued schedule.


scheduleRepeating

public Stoppable scheduleRepeating(Steppable event,
                                   int ordering,
                                   double interval)
Schedules the event to recur at the specified interval starting at time() + interval, and at the provided ordering. If this is a valid interval (must be positive) and event, schedules the event and returns a Stoppable, else returns null. The recurrence will continue until time() >= AFTER_SIMULATION, the Schedule is cleared out, or the Stoppable's stop() method is called, whichever happens first.

Note that calling stop() on the Stoppable will not only stop the repeating, but will also make the Schedule completely forget (lose the pointer to) the Steppable scheduled here. This is particularly useful if you need to make the Schedule NOT serialize certain Steppable objects. Do not use this with a real-valued schedule.


scheduleRepeating

public Stoppable scheduleRepeating(double time,
                                   Steppable event)
Schedules the event to recur at the specified interval starting at the provided time, and at 0 ordering. If the time() == the provided time, then the first event is instead scheduled to occur at time() + epsilon (the minimum possible next timestamp). If this is a valid time, ordering, interval (must be positive), and event, schedules the event and returns a Stoppable, else returns null. The recurrence will continue until time() >= AFTER_SIMULATION, the Schedule is cleared out, or the Stoppable's stop() method is called, whichever happens first.

Note that calling stop() on the Stoppable will not only stop the repeating, but will also make the Schedule completely forget (lose the pointer to) the Steppable scheduled here. This is particularly useful if you need to make the Schedule NOT serialize certain Steppable objects. Do not use this with a real-valued schedule.


scheduleRepeating

public Stoppable scheduleRepeating(double time,
                                   Steppable event,
                                   double interval)
Schedules the event to recur at the specified interval starting at the provided time, in ordering 0. If the time() == the provided time, then the first event is instead scheduled to occur at time() + epsilon (the minimum possible next timestamp). If this is a valid time, interval (must be positive), and event, schedules the event and returns a Stoppable, else returns null. The recurrence will continue until time() >= AFTER_SIMULATION, the Schedule is cleared out, or the Stoppable's stop() method is called, whichever happens first.

Note that calling stop() on the Stoppable will not only stop the repeating, but will also make the Schedule completely forget (lose the pointer to) the Steppable scheduled here. This is particularly useful if you need to make the Schedule NOT serialize certain Steppable objects. Do not use this with a real-valued schedule.


scheduleRepeating

public Stoppable scheduleRepeating(double time,
                                   int ordering,
                                   Steppable event)
Schedules the event to recur at an interval of 1.0 starting at the provided time, and in the ordering provided. If the time() == the provided time, then the first event is instead scheduled to occur at time() + epsilon (the minimum possible next timestamp). If this is a valid time, ordering, and event, schedules the event and returns a Stoppable, else returns null. The recurrence will continue until time() >= AFTER_SIMULATION, the Schedule is cleared out, or the Stoppable's stop() method is called, whichever happens first.

Note that calling stop() on the Stoppable will not only stop the repeating, but will also make the Schedule completely forget (lose the pointer to) the Steppable scheduled here. This is particularly useful if you need to make the Schedule NOT serialize certain Steppable objects. Do not use this with a real-valued schedule.


scheduleRepeating

public Stoppable scheduleRepeating(double time,
                                   int ordering,
                                   Steppable event,
                                   double interval)
Schedules the event to recur at the specified interval starting at the provided time, and in the ordering provided. If the time() == the provided time, then the first event is instead scheduled to occur at time() + epsilon (the minimum possible next timestamp). If this is a valid time, ordering, interval (must be positive), and event, schedules the event and returns a Stoppable, else returns null. The recurrence will continue until time() >= AFTER_SIMULATION, the Schedule is cleared out, or the Stoppable's stop() method is called, whichever happens first.

Note that calling stop() on the Stoppable will not only stop the repeating, but will also make the Schedule completely forget (lose the pointer to) the Steppable scheduled here. This is particularly useful if you need to make the Schedule NOT serialize certain Steppable objects. Do not use this with a real-valued schedule.