public class Sequence extends java.lang.Object implements Steppable
You provide Sequence with a Collection of Steppables, or with an array of Steppables, via its constructor. It then copies the Collection or array into its own internal array and uses that whenever you step it.
You can also modify the Steppables after the fact, in one of three ways. First, you can provide a new Collection or array to replace the internal array it is presently using, via the method replaceSteppables(...). Second, you can provide a collection of Steppables to be removed from the internal array, via the methods removeSteppable(...) or removeSteppables(...). Third, you can provide a collection of Steppables to be added to the internal array, via the methods addSteppable(...) or addSteppables(...). Sequence delays performing these actions until step(...) is called on it. At which time it first replaces the Steppabes with those provided by replaceSteppables(...), then removes any Steppables requested, then finally adds any Steppables requested. It then steps all the Steppables in the resulting internal array.
By default, after removing Steppables from the internal array, Sequence does not guarantee that the remaining Steppables will still be in the same order. It does this for speed. If you want to force them to be in the same order, you can call setEnsuresOrder(true). Note that even if the array has a consistent order internally, subclasses are free to ignore this: for example, RandomSequence and ParallelSequence do not keep the order consistent.
Removing Steppables is costly: the Sequence has to hunt through its array to find the ones you've asked to be removed, and that's O(n) per Steppable to remove. If you are often removing a fair number of Steppables (perhaps more than 5 at a time), Sequence provides a further option which results in O(1) removal: using an internal Set. The procedure is as follows: all the current Steppables, or the ones to relace them, are maintained in a LinkedHashSet. The Steppables to be removed are removed from the Set (O(1) per Steppable). Steppables to be added are then added to the Set. Finally the Set is dumped to an array, which is then Stepped.
To turn on this option, call setUsesSets(true).
This approach is dramatically faster than the default approach when a large number of Steppables are in the Sequence and at least a moderate number (5 or greater typically) is removed at a time. It has three disadvantages however. First, it is slower when the number of Steppables is very small, or when the number of Steppables removed is small (less than 5 perhaps). Second, because a Set is used, the Steppables in the Sequence must be unique: you cannot insert the same Steppable multiple times in the array. Third, using sets does not ensure order regardless of what you stated in setEnsuresOrder(...).
Modifier and Type | Field and Description |
---|---|
protected int |
size
The number of actual Steppables in the steps array.
|
protected Steppable[] |
steps
The internal Steppables to be stepped.
|
Constructor and Description |
---|
Sequence(java.util.Collection collection) |
Sequence(Steppable[] steps) |
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.
|
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.
|
protected void |
loadSteps()
Subclasses should call this method as more or less the first thing in their step(...) method.
|
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 |
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) |
protected Steppable[] steps
protected int size
public Sequence(Steppable[] steps)
public Sequence(java.util.Collection collection)
public boolean getEnsuresOrder()
public void setEnsuresOrder(boolean val)
protected boolean canEnsureOrder()
public boolean getUsesSets()
public void setUsesSets(boolean val)
protected void loadSteps()
public void replaceSteppables(java.util.Collection collection)
public void replaceSteppables(Steppable[] steppables)
public void addSteppable(Steppable steppable)
public void addSteppables(Steppable[] steppables)
public void addSteppables(java.util.Collection steppables)
public void removeSteppable(Steppable steppable)
public void removeSteppables(Steppable[] steppables)
public void removeSteppables(java.util.Collection steppables)