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 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 beyone 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.

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. You specify the number of orderings in the constructor, and can't change them thereafter. If you specify N orderings, then the ordering values are 0 ... N-1. 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. At present, you can't use an event of a lower ordering to schedule events of the same time in a higher ordering even though those events haven't occurred yet. Sorry.

Schedule is synchronized and threadsafe. It's easy enough to de-synchronize the schedule by hand if you would like to. In the worst case (schedule a single repeated steppable that does nothing), a synchronized schedule runs at 2/3 the speed of an unsynchronized schedule. In a typical case (such as HeatBugs), the difference between a synchronized and an unsynchronized schedule is less than 5% efficiency loss if it's visible at all.

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.

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
           
protected  int[] numSubsteps
           
protected  Heap[] queue
           
protected  long steps
           
protected  Steppable[][] substeps
           
protected  double time
           
 
Constructor Summary
Schedule()
          Creates a Schedule with a single order
Schedule(int numOrders)
           
 
Method Summary
protected  boolean _scheduleComplete()
           
 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.
protected  Steppable[] increaseSubsteps(Steppable[] substeps)
           
protected  Steppable[] increaseSubsteps(Steppable[] substeps, int n)
           
 void reset()
          Empties out the schedule and resets it to a pristine state BEFORE_SIMULATION, with steps = 0.
protected  void resetQueues(int numOrders)
           
 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.
 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.
 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

queue

protected Heap[] queue

substeps

protected Steppable[][] substeps

numSubsteps

protected int[] numSubsteps

time

protected double time

steps

protected long steps
Constructor Detail

Schedule

public Schedule(int numOrders)

Schedule

public Schedule()
Creates a Schedule with a single order

Method Detail

resetQueues

protected void resetQueues(int numOrders)

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()

increaseSubsteps

protected Steppable[] increaseSubsteps(Steppable[] substeps)

increaseSubsteps

protected Steppable[] increaseSubsteps(Steppable[] substeps,
                                       int n)

reset

public void reset()
Empties out the schedule and resets it to a pristine state BEFORE_SIMULATION, with steps = 0.


scheduleComplete

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


_scheduleComplete

protected boolean _scheduleComplete()

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(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.

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.

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.

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.

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.

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 nul.

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.