Template Class FiniteStateMachine¶
Defined in File FiniteStateMachine.hpp
Class Documentation¶
-
template<typename
Derived
, typename ...States
>
classActs
::
FiniteStateMachine
¶ 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). Tranitions 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 eventE
. Their values can be discarded (you can attach values to events of course, if you like) The return type of these functions is effectivelystd::optional<State>
, so you can either returnstd::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 toTerminated
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
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 tovoid on_enter(const State&); void on_exit(const State&);
Terminated
occurs.The base class also calls
during event processing, and allow for things like event and transition logging.void on_process(const Event&); void on_process(const State&, const Event&); void on_process(const State1& const Event&, const State2&);
The
on_event
,on_enter
,on_exit
andon_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 likeand so on.template <typename...Args> event_return on_event(Args&&...args) {} // noop
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 appropriateon_exit
andon_enter
overloads. Both also accept an arbitrary number of additional arguments that are passed to theon_event
,on_exit
andon_enter
overloads.- Template Parameters
Derived
: Class deriving from the FSMStates
: Argument pack with the state types that the FSM can be handled.
Public Types
-
using
StateVariant
= std::variant<Terminated, States...>¶ Variant type allowing tagged type erased storage of the current state of the FSM.
Public Functions
-
FiniteStateMachine
()¶ Default constructor.
The default state is taken to be the first in the
States
template arguments
-
FiniteStateMachine
(StateVariant state)¶ Constructor from an explicit state.
The FSM is initialized to this state.
- Parameters
state
: Initial state for the FSM.
-
template<typename
Event
, typename ...Args
>
voiddispatch
(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 triggeredArgs
: Additional arguments being passed to overload handlers.
- Parameters
event
: Instance of the event being triggereargs
: Additional arguments
-
const StateVariant &
getState
() const noexcept¶ Get the current state of of the FSM (as a variant).
- Return
StateVariant The current state of the FSM.
-
template<typename
S
>
boolis
(const S&) const noexcept¶ Returns whether the FSM is in the specified state.
- Return
Whether the FSM is in the given state.
- Template Parameters
State
: type to check against
- Parameters
state
: State instance to check against
-
template<typename
S
>
boolis
() const noexcept¶ Returns whether the FSM is in the specified state.
Alternative version directly taking only the template argument.
- Return
Whether the FSM is in the given state.
- Template Parameters
State
: type to check against
-
template<typename
State
, typename ...Args
>
voidsetState
(State state, Args&&... args)¶ Sets the state to a given one.
Triggers
on_exit
andon_enter
for the given states.- Template Parameters
State
: Type of the target stateArgs
: Additional arguments passed through callback overloads.
- Parameters
state
: Instance of the target stateargs
: The additional arguments
-
bool
terminated
() const noexcept¶ Returns whether the FSM is in the terminated state.
- Return
Whether the FSM is in the terminated state.
Protected Types
-
using
event_return
= std::optional<StateVariant>¶
-
using
fsm_base
= FiniteStateMachine<Derived, States...>¶
Protected Functions
-
template<typename
Event
, typename ...Args
>
event_returnprocess_event
(Event &&event, Args&&... args)¶ Handles processing of an event.
- Note
This should only be called from inside the class Deriving from FSM.
- Return
Variant state type, signifying if a transition is supposed to happen.
- Template Parameters
Event
: Type of the event being processedArgs
: Arguments being passed to the overload handlers.
- Parameters
event
: Instance of the eventargs
: Additional arguments