Acts::FiniteStateMachine< Derived, States > Class Template Reference

Implementation of a finite state machine engine. More...

#include <Acts/Utilities/FiniteStateMachine.hpp>

Inheritance diagram for Acts::FiniteStateMachine< Derived, States >:

Classes
struct	Terminated
	Contractual termination state. More...

Public Types
using	StateVariant = std::variant<Terminated, States...>
	Variant type allowing tagged type erased storage of the current state of the FSM.

Public Member Functions
	FiniteStateMachine ()
	Default constructor.
	FiniteStateMachine (StateVariant state)
	Constructor from an explicit state.
template<typename Event, typename... Args>
void	dispatch (Event &&event, Args &&... args)
	Public interface to handle an event.
const StateVariant &	getState () const noexcept
	Get the current state of the FSM (as a variant).
template<typename S>
bool	is () const noexcept
	Returns whether the FSM is in the specified state.
template<typename S>
bool	is (const S &) const noexcept
	Returns whether the FSM is in the specified state.
template<typename State, typename... Args>
void	setState (State state, Args &&... args)
	Sets the state to a given one.
bool	terminated () const noexcept
	Returns whether the FSM is in the terminated state.

Protected Types
using	event_return = std::optional<StateVariant>
	Type alias for event return type (optional state variant).
using	fsm_base = FiniteStateMachine<Derived, States...>
	Type alias for finite state machine base class.

Protected Member Functions
template<typename Event, typename... Args>
event_return	process_event (Event &&event, Args &&... args)
	Handles processing of an event.

Detailed Description

template<typename Derived, typename... States>
class Acts::FiniteStateMachine< Derived, States >

Implementation of a finite state machine engine.

Allows setting up a system of states and transitions between them. States are definedd as empty structs (footprint: 1 byte). Transitions call functions using overload resolution. This works by subclassing this class, providing the deriving type as the first template argument (CRTP) and providing methods like

event_return on_event(const S&, const E&);

The arguments are the state S and the triggered event E. Their values can be discarded (you can attach values to events of course, if you like) The return type of these functions is effectively std::optional<State>, so you can either return std::nullopt to remain in the same state, or an instance of another state. That state will then become active.

You can also define a method template, which will serve as a catch-all handler (due to the fact that it will match any state/event combination):

template <typename State, typename Event>
  event_return on_event(const State&, const Event&) const {
  return Terminated{};
}

If for a given state and event no suitable overload of on_event (and you also haven't defined a catch-all as described above), a transition to Terminated will be triggered. This is essentially equivalent to the method template above.

If this triggers, it will switch to the Terminated state (which is always included in the FSM).

Additionally, the FSM will attempt to call functions like

void on_enter(const State&);
void on_exit(const State&);

when entering/exiting a state. This can be used to perform actions regardless of the source or destination state in a transition to a given state. This is also fired in case a transition to Terminated occurs.

The base class also calls

void on_process(const Event&);
void on_process(const State&, const Event&);
void on_process(const State1& const Event&, const State2&);

during event processing, and allow for things like event and transition logging.

The on_event, on_enter, on_exit and on_process methods need to be implemented exhaustively, i.e. for all state/event combinations. This might require you to add catch-all no-op functions like

template <typename...Args>
event_return on_event(Args&&...args) {} // noop

and so on.

The public interface for the user of the FSM are the

template <typename... Args>
void setState(StateVariant state, Args&&... args);
 
template <typename Event, typename... Args>
void dispatch(Event&& event, Args&&... args) {

setState triggers a transition to a given state, dispatch triggers processing on an event from the given state. Both will call the appropriate on_exit and on_enter overloads. Both also accept an arbitrary number of additional arguments that are passed to the on_event, on_exit and on_enter overloads.

Template Parameters

Derived	Class deriving from the FSM
States	Argument pack with the state types that the FSM can be handled.

Constructor & Destructor Documentation

FiniteStateMachine() [1/2]

template<typename Derived, typename... States>

Acts::FiniteStateMachine< Derived, States >::FiniteStateMachine

(

)

Default constructor.

The default state is taken to be the first in the States template arguments

FiniteStateMachine() [2/2]

template<typename Derived, typename... States>

Acts::FiniteStateMachine< Derived, States >::FiniteStateMachine ( StateVariant state )

explicit

Constructor from an explicit state.

The FSM is initialized to this state.

Parameters

state

Initial state for the FSM.

Member Function Documentation

dispatch()

template<typename Derived, typename... States>

template<typename Event, typename... Args>

void Acts::FiniteStateMachine< Derived, States >::dispatch	(	Event &&	event,
		Args &&...	args )

Public interface to handle an event.

Will call the appropriate event handlers and perform any required transitions.

Template Parameters

Event	Type of the event being triggered
Args	Additional arguments being passed to overload handlers.

Parameters

event	Instance of the event being triggere
args	Additional arguments

getState()

template<typename Derived, typename... States>

const StateVariant & Acts::FiniteStateMachine< Derived, States >::getState ( ) const

noexcept

Get the current state of the FSM (as a variant).

Returns

StateVariant The current state of the FSM.

is() [1/2]

template<typename Derived, typename... States>

template<typename S>

bool Acts::FiniteStateMachine< Derived, States >::is ( ) const

noexcept

Returns whether the FSM is in the specified state.

Alternative version directly taking only the template argument.

Template Parameters

State

type to check against

Returns

Whether the FSM is in the given state.

is() [2/2]

template<typename Derived, typename... States>

template<typename S>

bool Acts::FiniteStateMachine< Derived, States >::is ( const S & ) const

noexcept

Returns whether the FSM is in the specified state.

Template Parameters

State

type to check against

Returns

Whether the FSM is in the given state.

process_event()

template<typename Derived, typename... States>

template<typename Event, typename... Args>

event_return Acts::FiniteStateMachine< Derived, States >::process_event ( Event && event, Args &&... args )

protected

Handles processing of an event.

Note

This should only be called from inside the class Deriving from FSM.

Template Parameters

Event	Type of the event being processed
Args	Arguments being passed to the overload handlers.

Parameters

event	Instance of the event
args	Additional arguments

Returns

Variant state type, signifying if a transition is supposed to happen.

setState()

template<typename Derived, typename... States>

template<typename State, typename... Args>

void Acts::FiniteStateMachine< Derived, States >::setState	(	State	state,
		Args &&...	args )

Sets the state to a given one.

Triggers on_exit and on_enter for the given states.

Template Parameters

State	Type of the target state
Args	Additional arguments passed through callback overloads.

Parameters

state	Instance of the target state
args	The additional arguments

terminated()

template<typename Derived, typename... States>

bool Acts::FiniteStateMachine< Derived, States >::terminated ( ) const

noexcept

Returns whether the FSM is in the terminated state.

Returns

Whether the FSM is in the terminated state.