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:

  1. Listen for the transition events (every time the machine successfully executes this transition).
  2. Attempt to execute this transition (will succeed so long as it is legal given the machine's current state and it isn't canceled).
  3. 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 and onDone 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