State Machine Composite State

Composite State

Composite State represents stable configuration of State Machine that also contains its own set of States (referred to as its substates). Composite State is the way to introduce State nesting concept to defined State Machine.

Composite State can be seen as Orthogonal State with exactly one Region - no orthogonality (parallelism), just nesting of States.

Composite State consist of:

• Name, uniquely identifying State within State Machine,
• Parent State, if State is a substate of Composite State or Orthogonal State,
• OnEntry, logic that is executed when State is entered,
• OnExit, logic that is executed when State is exited,
• OnInitialize, logic that is executed when State is initialized,
• OnFinalize, logic that is executed when State is finalized,
• Set of outgoing Transitions.
• Set of States with their outgoing Transitions.

Definition

In UML, Composite State is represented by rounded rectangle that is also a container for other States:

stateDiagram-v2
state CompositeState {
  direction LR
  Substate1 --> Substate2
}

Loading

Composite State may also contain one initial pseudostate:

stateDiagram-v2
state CompositeState {
  direction LR
  [*] --> Substate
}

Loading

Equivalent Stateflows notation of States:

Lambda style

Definition fragment (inside the builder callback):

    /* fragment of State Machine definition */
    .AddCompositeState("CompositeState", b => b
        .AddOnEntry(c => Task.CompletedTask)
        .AddOnExit(c => Task.CompletedTask)

        .AddInitialState("Substate")
    )

Using lambda style here means that State is referred to by string name and each bit of State logic is implemented as lambda function passed as parameters to AddOn* methods in State definition.

Typed style

    public class CompositeState : ICompositeStateEntry, ICompositeStateExit
    {
        public async Task OnEntryAsync()
        {
            /* logic here */
        }

        public async Task OnExitAsync()
        {
            /* logic here */
        }
    }

    public class Substate : IState
    { }

Definition fragment (inside the builder callback):

    /* fragment of State Machine definition */
    .AddCompositeState<CompositeState>(b => b
        .AddInitialState<Substate>()
    )

Using typed style here means that State is a class that is referenced in typed overloads of AddOn* methods in State Machine definition.

Class can be used as Composite State if it implements at least one interface from ICompositeState* family:

• ICompositeState - simply represents Composite State,
• ICompositeStateEntry - represents Composite State with OnEntry logic implemented as OnEntryAsync() method,
• ICompositeStateExit - represents Composite State with OnExit logic implemented as OnExitAsync() method,
• ICompositeStateInitialization - represents Composite State with OnInitialize logic implemented as OnInitializeAsync() method,
• ICompositeStateFinalization - represents Composite State with OnFinalize logic implemented as OnFinalizeAsync() method,
• ICompositeStateDefinition - represents Composite State with additional Build() method that allows to extend its definition, for example to define Transitions within State class.

Initialization and finalization actions

Composite states may define OnInitialize and OnFinalize actions. Initialization runs when the composite state initializes its child configuration; finalization runs when that configuration reaches its final state. The typed interfaces are ICompositeStateInitialization and ICompositeStateFinalization; lambda definitions use AddOnInitialize and AddOnFinalize.

Orthogonal states provide the corresponding callbacks for their region configuration. These callbacks are distinct from the state's ordinary entry and exit actions.

State logic may also be split into several classes like in the example:

    public class SimpleState : IState
    { }

    public class SimpleEntry : IStateEntry
    {
        public async Task OnEntryAsync()
        {
            /* logic here */
        }
    }

    public class SimpleExit : IStateExit
    {
        public async Task OnExitAsync()
        {
            /* logic here */
        }
    }

    public class AnotherState : IState
    { }

Definition fragment (inside the builder callback):

    /* fragment of State Machine definition */
    .AddState<SimpleState>(b => b
        .AddOnEntry<SimpleEntry>()
        .AddOnExit<SimpleExit>()

        .AddDefaultTransition<AnotherState>()
    )
    .AddState<AnotherState>()

This technique enables reusing of State's logic, but there is an important concern of State identity to be considered.