TreeStateMachine class

A state machine that manages transitions among the states in a state tree.

A TreeStateMachine is constructed with a StateTreeBuilder that will create the specific tree of states that the state machine manages. After the state machine is constructed, calling start will enter the initial state for the tree, and return a CurrentState that serves as a proxy for the current state of the state tree. CurrentState.post can be used to send a message to the state for processing, which may result in a transition to a new state.

  var stateTreeBuilder = createTreeBuilder();
  var stateMachine = TreeStateMachine(stateTreeBuilder);

  var currentState = await stateMachine.start();
  print('The current state is ${currentState.key}');

  var messageProcessed = await currentState.post(MyMessage());
  print('The current state after processing a message is ${currentState.key}');

When the machine is started, the machine determines determine a path of states, starting at the root and ending at a leaf state, by recursively determining the initialChild at each level of the tree until a state with no children is reached. This path of states is called the initial path, and the machine will call onEnter for each state along this path. When all the states along the path have been entered, the state at the end of the path becomes the current state of the state machine.

Event Streams

TreeStateMachine provides several event streams that may be used to observe how messages sent to the machine are processed, and what state transitions occur.

• processedMessages yields an event for every message that is processed by the tree, whether or not the message was handled successfully, and whether or not a transition occurred as a result of the message.
• handledMessages is a convenience stream that yield an event when only when a message is successfully handled.
• transitions yields an event each time a transition between states occurs.

Error Handling

Errors may occur when as state processes a message. This can happen in the TreeState.onMessage handler while the state is processing the message, or it can happen during a state transition in the TreeState.onExit handler of one of the states that is being exited, or in the TreeState.onEnter handler of one of the states that is being entered.

In either case the state machine catches the error internally, converts it to a FailedMessage, and yields it from he future returned from CurrentState.post. The FailedMessage is also emitted on he failedMessages stream.

See also:

• UML State Machines, for background information on UML (hierarchical) state machines.
• State Machine Diagrams, for further description of UML state machine diagrams.