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 ParallelSequence

    java.lang.Object
      sim.engine.Sequence
          sim.engine.ParallelSequence

All Implemented Interfaces:
  java.io.Serializable, Steppable

    public class ParallelSequence

extends Sequence

Spawns all the sequence elements in parallel on separate threads. This should ONLY be used if you know that all of the elements in the sequence can be executed independently of one another without any race conditions. No synchronization on the model data is done -- you're responsible for that if you need it.

For example, keep in mind that the random number generator is unsynchronized. You should not embed RandomSequences inside a ParallelSequence unless you've set their shouldSynchronize value to true, and elsewhere in your embedded steppables you're synchronizing on the Schedule first (the Schedule is the basic lock point for MASON's models).

ParallelSequences are lightweight: they reuse the same threads if stepped repeatedly. This means that you must never attach a ParallelSequence inside itself -- that'd be an infinite loop, but it also would create weird thread errors.

While ParallelSequences might LOOK cool, generally speaking the only time you should ever think to use them is if you actually HAVE multiple CPUs on your computer. Otherwise they're almost certainly not the solution to your odd multiple-thread needs.

Important Note Because ParallelSequences are lightweight, their threads are persistent, even after your step() method has completed (this allows them to be reused for the next step() method. If the ParallelSequence is garbage collected, we automatically delete all its threads in its finalize() method. And that's the rub: even if you get rid of your ParallelSequence, it's often the case that its garbage collection is delayed, or even that the VM will never garbage collect it.

Thus when you're done with your ParallelSequence and wish to throw it away, you should always call cleanup(), which deletes the threads manually. Otherwise the thread resources will leak and quickly consume all your available memory.

Alternatively you can call setDestroysThreads(true) on your ParallelSequence. This will cause the ParallelSequence to destroy its threads every single time the ParallelSequence's step() method completes. This is expensive but you don't have to keep track of the ParallelSequence at the end of the run to call cleanup() on it. It's not a bad idea for a ParallelSequence which is one-shot rather than repeating.

See Also:
  Serialized Form

Field Summary
`static int` | `CPUS` Indicates that MASON should determine how many threads to use based on the number of CPUs.

Fields inherited from class sim.engine.Sequence
`steps`

Constructor Summary
`ParallelSequence(Steppable[] steps)` Creates a ParallelSequence with one thread per steppable.
`ParallelSequence(Steppable[] sequence, int threads)` Creates a ParallelSequence with the specified number of threads, or if threads==ParallelSequence.CPUS, then the number of threads is determined at runtime based on the number of CPUs or cores on the system.

Method Summary
`void` | `cleanup()` Call this just before you get rid of a ParallelSequence: for example, one good place is the stop() method of your simulation.
`protected void` | `finalize()`
`Steppable` | `getCleaner()`
`boolean` | `getDestroysThreads()`
`void` | `setDestroysThreads(boolean val)`
`void` | `step(SimState state)`

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

Field Detail

### CPUS

    public static final int CPUS

  Indicates that MASON should determine how many threads to use based on the number of CPUs.

  See Also:
    Constant Field Values

Constructor Detail

### ParallelSequence

    public ParallelSequence(Steppable[] sequence,
                            int threads)

  Creates a ParallelSequence with the specified number of threads, or if threads==ParallelSequence.CPUS, then the number of threads is determined at runtime based on the number of CPUs or cores on the system. The steppable objects are divided approximately evenly among the various threads.

### ParallelSequence

    public ParallelSequence(Steppable[] steps)

  Creates a ParallelSequence with one thread per steppable.

Method Detail

### getDestroysThreads

    public boolean getDestroysThreads()

### setDestroysThreads

    public void setDestroysThreads(boolean val)

### getCleaner

    public Steppable getCleaner()

### cleanup

    public void cleanup()

  Call this just before you get rid of a ParallelSequence: for example, one good place is the stop() method of your simulation. Never call this method inside the ParallelSequence's own step() method. This method deletes the threads so the ParallelSequence is ready to be thrown away. We also do this in finalize() but finalize() is not guaranteed to be called at any particular time, which can result in unexpected memory leaks. Think of this method as the same kind of thing as a Graphics or Window's dispose() method.

### finalize

    protected void finalize()
                     throws java.lang.Throwable

  Overrides:
    `finalize` in class `java.lang.Object`
  Throws:
    `java.lang.Throwable`

### step

    public void step(SimState state)

  Specified by:
    `step` in interface `Steppable`
  Overrides:
    `step` in class `Sequence`

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