StateTransition class
Represents a legal state transition for a StateMachine instance.
State transitions must be created from a StateMachine instance and must define the set of legal "from" states and a single "to" state. The machine must be in one of the "from" states in order for this transition to occur.
StateMachine door = new StateMachine('door');
State isOpen = door.newState('open');
State isClosed = door.newState('closed');
StateTransition open = door.newStateTransition('open', [isClosed], isOpen);
StateTransition close = door.newStateTransition('close', [isOpen], isClosed);
door.start(isClosed);
There are 3 things that can be done with state transitions:
- Listen for the transition events (every time the machine successfully executes this transition).
- Attempt to execute this transition (will succeed so long as it is legal given the machine's current state and it isn't canceled).
- Add conditions that can cancel this transition.
To demonstrate:
// 1.
open.listen((StateChange change) {
// transition stream event always includes the previous state,
// since transitions can define multiple legal "from" states.
print('Door opened.');
});
// 2.
open(); // returns `true` since the transition was legal and succeeded.
// 3.
close.cancelIf((StateChange change) => true); // will cancel the close transition every time
close(); // returns `false` since it was canceled
To get a better idea of how state transitions can be used, consider the following example that integrates two separate state machines to represent the state of a lamp.
StateMachine powerCord = new StateMachine('powerCord');
State isPluggedIn = powerCord.newState('pluggedIn');
State isUnplugged = powerCord.newState('unplugged');
StateTransition plugIn = powerCord.newStateTransition('plugIn', [isUnplugged], isPluggedIn);
StateTransition unplug = powerCord.newStateTransition('unplug', [isPluggedIn], isUnplugged);
StateMachine lamp = new StateMachine('lamp');
State isOn = lamp.newState('on');
State isOff = lamp.newState('off');
StateTransition turnOn = lamp.newStateTransition('turnOn', [isOff], isOn);
StateTransition turnOff = lamp.newStateTransition('turnOff', [isOn], isOff);
// When the power cord is unplugged, transition the lamp to the
// "off" state if it is currently "on".
unplug.listen((_) {
if (isOn()) {
turnOff();
}
});
// The lamp cannot be turned on if the power cord is unplugged.
turnOn.cancelIf(isUnplugged);
isOn.onEnter.listen((_) => print('Light is on!'));
isOn.onLeave.listen((_) => print('Light is off :('));
powerCord.start(isUnplugged);
lamp.start(isOff);
turnOn(); // canceled, no power
plugIn();
turnOn(); // "Light is on!"
unplug(); // "Light is off :("
Properties
-
didDispose
→ Future<
Null> -
A Future that will complete when this object has been disposed.
no setterinherited
- disposableTypeName → String
-
A type name, similar to runtimeType but intended to work
with minified code.
no setter
- disposalTreeSize → int
-
The total size of the disposal tree rooted at the current Disposable
instance.
no setterinherited
- hashCode → int
-
The hash code for this object.
no setterinherited
- isDisposed → bool
-
Whether this object has been disposed.
no setterinherited
- isLeakFlagSet → bool
-
Whether the leak flag for this object has been set.
no setterinherited
- isOrWillBeDisposed → bool
-
Whether the disposal of this object has been requested, is in progress, or
is complete.
no setterinherited
- name ↔ String
-
Name of the state transition. Used for debugging.
getter/setter pair
- runtimeType → Type
-
A representation of the runtime type of the object.
no setterinherited
-
stream
→ Stream<
StateChange> -
Stream of transition events. A transition event occurs every time this
transition executes successfully.
no setter
Methods
-
awaitBeforeDispose<
T> (Future< T> future) → Future<T> -
Add
future
to a list of futures that will be awaited before the object is disposed.inherited -
call(
[dynamic payload]) → bool - Execute this transition. Will call any tests registered via cancelIf, canceling the transition if any test returns true. Otherwise, the transition will occur and the machine will transition accordingly.
-
canCall(
[dynamic payload]) → bool - Execute all the pre-checks to understand if a transition can take place or not. Will call any tests registered via cancelIf, canceling the transition if any test returns true.
-
cancelIf(
bool test(StateChange stateChange)) → void -
Add a test that will be called before executing
this transition. If
test
returns true, the transition will be canceled. -
dispose(
) → Future< Null> -
Dispose of the object, cleaning up to prevent memory leaks.
inherited
-
flagLeak(
[String? description]) → void -
Flag the object as having been disposed in a way that allows easier
profiling.
inherited
-
getManagedDelayedFuture<
T> (Duration duration, T callback()) → Future< T> -
Creates a Future that will complete, with the value
returned by
callback
, after the given amount of time has elapsed.inherited -
getManagedDisposer(
Disposer disposer) → ManagedDisposer -
Automatically handle arbitrary disposals using a callback.
inherited
-
getManagedPeriodicTimer(
Duration duration, void callback(Timer timer)) → Timer -
Creates a periodic Timer that will be cancelled if active
upon disposal.
inherited
-
getManagedTimer(
Duration duration, void callback()) → Timer -
Creates a Timer instance that will be cancelled if active
upon disposal.
inherited
-
listen(
void onTransition(StateChange stateChange), {Function? onError, void onDone()?, bool? cancelOnError}) → StreamSubscription - Listen for transition events. Transition event occurs every time this transition executes successfully.
-
listenToStream<
T> (Stream< T> stream, void onData(T event), {Function? onError, void onDone()?, bool? cancelOnError}) → StreamSubscription<T> -
Returns a StreamSubscription which handles events from the stream using
the provided
onData
,onError
andonDone
handlers.inherited -
manageAndReturnTypedDisposable<
T extends Disposable> (T disposable) → T -
Automatically dispose another object when this object is disposed.
inherited
-
manageCompleter<
T> (Completer< T> completer) → Completer<T> -
Ensure that a completer is completed when the object is disposed.
inherited
-
manageDisposable(
Disposable disposable) → void -
inherited
-
manageStreamController(
StreamController controller) → void -
Automatically cancel a stream controller when this object is disposed.
inherited
-
noSuchMethod(
Invocation invocation) → dynamic -
Invoked when a nonexistent method or property is accessed.
inherited
-
onDispose(
) → Future< Null> -
Callback to allow arbitrary cleanup on dispose.
inherited
-
onWillDispose(
) → Future< Null> -
Callback to allow arbitrary cleanup as soon as disposal is requested (i.e.
dispose is called) but prior to disposal actually starting.
inherited
-
toString(
) → String -
A string representation of this object.
override
Operators
-
operator ==(
Object other) → bool -
The equality operator.
inherited