public class ParallelSequence extends Sequence
For example, keep in mind that the random number generator is unsynchronized. If you access the random number generator from within a ParallelSequence, or indeed from multiple threads you've spawned in other situations, you need to remember to lock on the random number generator itself.
In the same vein, if you use a RandomSequence within a ParallelSequence, you need to let the RandomSequence know this so that it will lock on the random number generator properly. This is done by setting the shouldSynchronize flag in the RandomSequence.
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.
Be sure to read the class documentation on sim.engine.Sequence
Modifier and Type | Field and Description |
---|---|
static int |
CPUS
Indicates that MASON should determine how many threads to use based on the number of CPUs.
|
static int |
STEPPABLES |
Constructor and Description |
---|
ParallelSequence(java.util.Collection steps)
Creates an immutable ParallelSequence with one thread per steppable in the collection.
|
ParallelSequence(java.util.Collection steps,
int threads)
Creates an immutable 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, or if threads == ParallelSequence.STEPPABLES, then the number of threads
is the size of the collection passed in (and may change as the collection grows or shrinks).
|
ParallelSequence(Steppable[] steps)
Creates an immutable ParallelSequence with one thread per steppable.
|
ParallelSequence(Steppable[] steps,
int threads)
Creates an immutable 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, or if threads == ParallelSequence.STEPPABLES, then the number of threads
is the size of the steps array passed in.
|
Modifier and Type | Method and Description |
---|---|
void |
addSteppable(Steppable steppable)
Requests that the provided Steppable be added to the Sequence prior to the next step() call.
|
void |
addSteppables(java.util.Collection steppables)
Requests that the provided Steppables be added to the Sequence prior to the next step() call.
|
void |
addSteppables(Steppable[] steppables)
Requests that the provided Steppables be added to the Sequence prior to the next step() call.
|
protected boolean |
canEnsureOrder()
If your subclass does not respect order, override this method to return
false, and Sequence will ignore the ensuresOrder result.
|
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() |
boolean |
getEnsuresOrder()
Returns whether the order among the remaining Steppables in the internal array is maintained after removing
Steppables via removeSteppable() or removeSteppables().
|
boolean |
getUsesSets()
Returns whether the Sequence uses a Set internally to manage the internal array.
|
void |
removeSteppable(Steppable steppable)
Requests that the provided Steppable be removed from the Sequence prior to the next step() call.
|
void |
removeSteppables(java.util.Collection steppables)
Requests that the provided Steppables be removed from the Sequence prior to the next step() call.
|
void |
removeSteppables(Steppable[] steppables)
Requests that the provided Steppables be removed from the Sequence prior to the next step() call.
|
void |
replaceSteppables(java.util.Collection collection)
Requests that the provided Steppables replace the existing Steppables in the internal array prior to the next step() call.
|
void |
replaceSteppables(Steppable[] steppables)
Requests that the provided Steppables replace the existing Steppables in the internal array prior to the next step() call.
|
void |
setDestroysThreads(boolean val) |
void |
setEnsuresOrder(boolean val)
Sets whether the order among the remaining Steppables in the internal array is maintained after removing
Steppables via removeSteppable() or removeSteppables().
|
void |
setUsesSets(boolean val)
Sets whether the Sequence uses a Set internally to manage the internal array.
|
void |
step(SimState state) |
public static final int CPUS
public static final int STEPPABLES
public ParallelSequence(Steppable[] steps, int threads)
public ParallelSequence(Steppable[] steps)
public ParallelSequence(java.util.Collection steps, int threads)
public ParallelSequence(java.util.Collection steps)
public boolean getDestroysThreads()
public void setDestroysThreads(boolean val)
public Steppable getCleaner()
public void cleanup()
protected void finalize() throws java.lang.Throwable
finalize
in class java.lang.Object
java.lang.Throwable
protected boolean canEnsureOrder()
Sequence
canEnsureOrder
in class Sequence
public void step(SimState state)
public void replaceSteppables(java.util.Collection collection)
Sequence
replaceSteppables
in class Sequence
public void replaceSteppables(Steppable[] steppables)
Sequence
replaceSteppables
in class Sequence
public void addSteppable(Steppable steppable)
Sequence
addSteppable
in class Sequence
public void addSteppables(Steppable[] steppables)
Sequence
addSteppables
in class Sequence
public void addSteppables(java.util.Collection steppables)
Sequence
addSteppables
in class Sequence
public void removeSteppable(Steppable steppable)
Sequence
removeSteppable
in class Sequence
public void removeSteppables(Steppable[] steppables)
Sequence
removeSteppables
in class Sequence
public void removeSteppables(java.util.Collection steppables)
Sequence
removeSteppables
in class Sequence
public boolean getEnsuresOrder()
Sequence
getEnsuresOrder
in class Sequence
public void setEnsuresOrder(boolean val)
Sequence
setEnsuresOrder
in class Sequence
public boolean getUsesSets()
Sequence
getUsesSets
in class Sequence
public void setUsesSets(boolean val)
Sequence
setUsesSets
in class Sequence