Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## sim.engine
Class SimState

    java.lang.Object
      sim.engine.SimState

All Implemented Interfaces:
  java.io.Serializable

    public class SimState

extends java.lang.Object
implements java.io.Serializable

SimState represents the simulation proper. Your simulations generally will contain one top-level object which subclasses from SimState.

A SimState contains the random number generator and the simulator's schedule. You should not change the schedule to another Schedule object.

When a simulation is begun, SimState's start() method is called. Then the schedule is stepped some N times. Last, the SimState's finish() method is called, and the simulation is over.

SimStates are serializable; if you wish to be able to checkpoint your simulation and read from checkpoints, you should endeavor to make all objects in the simulation serializable as well. Prior to serializing to a checkpoint, preCheckpoint() is called. Then after serialization, postCheckpoint() is called. When a SimState is loaded from a checkpoint, awakeFromCheckpoint() is called to give you a chance to make any adjustments. SimState also implements several methods which call these methods and then serialize the SimState to files and to streams.

SimState also maintains a private registry of AsynchronousSteppable objects (such as YoYoYo), and handles pausing and resuming them during the checkpointing process, and killing them during finish() in case they had not completed yet.

If you override any of the methods foo() in SimState, should remember to always call super.foo() for any such method foo().

See Also:
  Serialized Form

Field Summary
`boolean` | `cleaningAsynchronous`
`MersenneTwisterFast` | `random` The SimState's random number generator
`Schedule` | `schedule` SimState's schedule

Constructor Summary
`SimState(long seed)` Creates a SimState with a new random number generator initialized to the given seed, plus a new, empty schedule.
`SimState(MersenneTwisterFast random)` Creates a SimState with a new, empty Schedule and the provided random number generator.
`SimState(MersenneTwisterFast random, Schedule schedule)` Creates a SimState with the provided random number generator and schedule.

Method Summary
`boolean` | `addToAsynchronousRegistry(AsynchronousSteppable stop)` Registers an AsynchronousSteppable to get its pause() method called prior to checkpointing, its resume() method to be called after checkpointing or recovery, and its stop() method to be called at finish() time.
`AsynchronousSteppable[]` | `asynchronousRegistry()` Returns all the AsynchronousSteppable items presently in the registry.
`void` | `awakeFromCheckpoint()` Called after the SimState was created by reading from a checkpointed object.
`static void` | `doLoop(java.lang.Class c, java.lang.String[] args)` Calls doLoop(MakesSimState,args), passing in a MakesSimState which creates SimStates of the provided Class c, using the constructor new ().
`static void` | `doLoop(MakesSimState generator, java.lang.String[] args)` A convenient top-level loop for the simulation command-line.
`void` | `finish()` Called either at the proper or a premature end to the simulation.
`long` | `job()` Returns the job number set by the doLoop(...) facility.
`void` | `kill()` A Steppable on the schedule can call this method to cancel the simulation.
`static void` | `nameThread(SimState state)` Names the current thread an appropriate name given the SimState
`void` | `postCheckpoint()` Called just after the SimState was checkpointed (serialized out to a file to be unserialized and fired up at a future time).
`void` | `preCheckpoint()` Called just before the SimState is being checkpointed (serialized out to a file to be unserialized and fired up at a future time).
`static SimState` | `readFromCheckpoint(java.io.File file)` Creates a SimState from checkpoint.
`static SimState` | `readFromCheckpoint(java.io.InputStream stream)` Creates and returns a new SimState object read in from the provided stream.
`void` | `removeFromAsynchronousRegistry(AsynchronousSteppable stop)` Unregisters an AsynchronousSteppable from the asynchronous registry.
`long` | `seed()` Returns the seed set by the doLoop(...) facility and by the constructor.
`void` | `setRandom(MersenneTwisterFast random)`
`void` | `start()` Called immediately prior to starting the simulation, or in-between simulation runs.
`static double` | `version()`
`SimState` | `writeToCheckpoint(java.io.File file)` Writes the state to a checkpoint and returns the state.
`void` | `writeToCheckpoint(java.io.OutputStream stream)` Serializes out the SimState, and the entire simulation state (not including the graphical interfaces) to the provided stream.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### random

    public MersenneTwisterFast random

  The SimState's random number generator

### schedule

    public Schedule schedule

  SimState's schedule

### cleaningAsynchronous

    public boolean cleaningAsynchronous

Constructor Detail

### SimState

    public SimState(long seed)

  Creates a SimState with a new random number generator initialized to the given seed, plus a new, empty schedule.

### SimState

    public SimState(MersenneTwisterFast random)

  Creates a SimState with a new, empty Schedule and the provided random number generator.

### SimState

    public SimState(MersenneTwisterFast random,
                    Schedule schedule)

  Creates a SimState with the provided random number generator and schedule.

Method Detail

### setRandom

    public void setRandom(MersenneTwisterFast random)

### start

    public void start()

  Called immediately prior to starting the simulation, or in-between simulation runs. This gives you a chance to set up initially, or reset from the last simulation run. The default version simply replaces the Schedule with a completely new one.

### finish

    public void finish()

  Called either at the proper or a premature end to the simulation. If the user quits the program, this function may not be called. It is possible for this method to be called multiple times. If you need to check for this possibility, the easiest way is to set a flag in start() and clear it in the first finish().

### kill

    public void kill()

  A Steppable on the schedule can call this method to cancel the simulation. All existing YoYoYos are stopped, and then the schedule is reset. YoYoYos, ParallelSteppables, and non-main threads should not call this method directly -- it will deadlock. Instead, they may kill the simulation by scheduling a Steppable for the next timestep which calls state.kill().

### addToAsynchronousRegistry

    public boolean addToAsynchronousRegistry(AsynchronousSteppable stop)

  Registers an AsynchronousSteppable to get its pause() method called prior to checkpointing, its resume() method to be called after checkpointing or recovery, and its stop() method to be called at finish() time. The purpose of the addToCleanup() method is to provide the simulation with a way of stopping existing threads which the user has created in the background.

  An AsynchronousSteppable cannot be added multiple times to the same registry -- if it's there it's there. Returns false if the AsynchronousSteppable could not be added, either because the simulation is stopped or in the process of finish()ing.

### removeFromAsynchronousRegistry

    public void removeFromAsynchronousRegistry(AsynchronousSteppable stop)

  Unregisters an AsynchronousSteppable from the asynchronous registry.

### asynchronousRegistry

    public AsynchronousSteppable[] asynchronousRegistry()

  Returns all the AsynchronousSteppable items presently in the registry. The returned array is not used internally -- you are free to modify it.

### preCheckpoint

    public void preCheckpoint()

  Called just before the SimState is being checkpointed (serialized out to a file to be unserialized and fired up at a future time). You should override this to prepare your SimState object appropriately. Be sure to call super.preCheckpoint().

### postCheckpoint

    public void postCheckpoint()

  Called just after the SimState was checkpointed (serialized out to a file to be unserialized and fired up at a future time). You cam override this as you see fit. Be sure to call super.postCheckpoint().

### awakeFromCheckpoint

    public void awakeFromCheckpoint()

  Called after the SimState was created by reading from a checkpointed object. You should set up your SimState in any way necessary (reestablishing file connections, etc.) to fix anything that may no longer exist. Be sure to call super.awakeFromCheckpoint().

### writeToCheckpoint

    public void writeToCheckpoint(java.io.OutputStream stream)
                           throws java.io.IOException

  Serializes out the SimState, and the entire simulation state (not including the graphical interfaces) to the provided stream. Calls preCheckpoint() before and postCheckpoint() afterwards. Throws an IOException if the stream becomes invalid (prematurely closes, etc.). Does not close or flush the stream.

  Throws:
    `java.io.IOException`

### writeToCheckpoint

    public SimState writeToCheckpoint(java.io.File file)

  Writes the state to a checkpoint and returns the state. If an exception is raised, it is printed and null is returned.

### readFromCheckpoint

    public static SimState readFromCheckpoint(java.io.File file)

  Creates a SimState from checkpoint. If an exception is raised, it is printed and null is returned.

### readFromCheckpoint

    public static SimState readFromCheckpoint(java.io.InputStream stream)
                                       throws java.io.IOException,
                                              java.lang.ClassNotFoundException,
                                              java.io.OptionalDataException,
                                              java.lang.ClassCastException

  Creates and returns a new SimState object read in from the provided stream. Calls awakeFromCheckpoint(). Throws an IOException if the stream becomes invalid (prematurely closes etc.). Throws a ClassNotFoundException if a serialized object is not found in the CLASSPATH and thus cannot be created. Throws an OptionalDataException if the stream is corrupted. Throws a ClassCastException if the top-level object is not actually a SimState. Does not close or flush the stream.

  Throws:
    `java.io.IOException`
    `java.lang.ClassNotFoundException`
    `java.io.OptionalDataException`
    `java.lang.ClassCastException`

### seed

    public long seed()

  Returns the seed set by the doLoop(...) facility and by the constructor. Only to be used for GUIs to display possible seed values.

### job

    public long job()

  Returns the job number set by the doLoop(...) facility. This number is not incremented by the GUI.

### doLoop

    public static void doLoop(java.lang.Class c,
                              java.lang.String[] args)

  Calls doLoop(MakesSimState,args), passing in a MakesSimState which creates SimStates of the provided Class c, using the constructor new ().

### doLoop

    public static void doLoop(MakesSimState generator,
                              java.lang.String[] args)

  A convenient top-level loop for the simulation command-line. Takes a MakesSimState which is responsible for providing a SimState to run the simulation on, plus the application's argument list in args. This loop is capable of:
  - Repeating a job multiple times

### nameThread

    public static void nameThread(SimState state)

  Names the current thread an appropriate name given the SimState

### version

    public static double version()

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD