 |
ACTS
Experiment-independent tracking
|
|
ACTS
Experiment-independent tracking
|
Implementation of a finite state machine engine. More...
#include <Acts/Utilities/FiniteStateMachine.hpp>
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. | |
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
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):
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
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
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
and so on.
The public interface for the user of the FSM are the
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.
| Derived | Class deriving from the FSM |
| States | Argument pack with the state types that the FSM can be handled. |
|
protected |
Type alias for event return type (optional state variant).
|
protected |
Type alias for finite state machine base class.
| using Acts::FiniteStateMachine< Derived, States >::StateVariant = std::variant<Terminated, States...> |
Variant type allowing tagged type erased storage of the current state of the FSM.
| Acts::FiniteStateMachine< Derived, States >::FiniteStateMachine | ( | ) |
Default constructor.
The default state is taken to be the first in the States template arguments
|
explicit |
Constructor from an explicit state.
The FSM is initialized to this state.
| state | Initial state for the FSM. |
| 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.
| Event | Type of the event being triggered |
| Args | Additional arguments being passed to overload handlers. |
| event | Instance of the event being triggere |
| args | Additional arguments |
|
noexcept |
Get the current state of the FSM (as a variant).
|
noexcept |
Returns whether the FSM is in the specified state.
Alternative version directly taking only the template argument.
| State | type to check against |
|
noexcept |
Returns whether the FSM is in the specified state.
| State | type to check against |
|
protected |
Handles processing of an event.
| Event | Type of the event being processed |
| Args | Arguments being passed to the overload handlers. |
| event | Instance of the event |
| args | Additional arguments |
| 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.
| State | Type of the target state |
| Args | Additional arguments passed through callback overloads. |
| state | Instance of the target state |
| args | The additional arguments |
|
noexcept |
Returns whether the FSM is in the terminated state.
1.15.0