ECCE @ EIC Software
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Acts::FiniteStateMachine< Derived, States > Class Template Reference

#include <acts/blob/master/Core/include/Acts/Utilities/FiniteStateMachine.hpp>

Classes

struct  Terminated
 

Public Types

using StateVariant = std::variant< Terminated, States...>
 

Public Member Functions

 FiniteStateMachine ()
 
 FiniteStateMachine (StateVariant state)
 
const StateVariantgetState () const noexcept
 
template<typename State , typename... Args>
void setState (State state, Args &&...args)
 
template<typename S >
bool is (const S &) const noexcept
 
template<typename S >
bool is () const noexcept
 
bool terminated () const noexcept
 
template<typename Event , typename... Args>
void dispatch (Event &&event, Args &&...args)
 

Protected Types

using fsm_base = FiniteStateMachine< Derived, States...>
 
using event_return = std::optional< StateVariant >
 

Protected Member Functions

template<typename Event , typename... Args>
event_return process_event (Event &&event, Args &&...args)
 

Private Attributes

StateVariant m_state
 

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). 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

```cpp 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):

```cpp 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 ```cpp 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 ```cpp 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 ```cpp template <typename...Args> event_return on_event(Args&&...args) {} // noop ``` and so on.

The public interface for the user of the FSM are the ```cpp 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
DerivedClass deriving from the FSM
StatesArgument pack with the state types that the FSM can be handled.

Definition at line 102 of file FiniteStateMachine.hpp.

View newest version in sPHENIX GitHub at line 102 of file FiniteStateMachine.hpp

Member Typedef Documentation

template<typename Derived, typename... States>
using Acts::FiniteStateMachine< Derived, States >::event_return = std::optional<StateVariant>
protected

Definition at line 118 of file FiniteStateMachine.hpp.

View newest version in sPHENIX GitHub at line 118 of file FiniteStateMachine.hpp

template<typename Derived, typename... States>
using Acts::FiniteStateMachine< Derived, States >::fsm_base = FiniteStateMachine<Derived, States...>
protected

Definition at line 116 of file FiniteStateMachine.hpp.

View newest version in sPHENIX GitHub at line 116 of file FiniteStateMachine.hpp

template<typename Derived, typename... States>
using Acts::FiniteStateMachine< Derived, States >::StateVariant = std::variant<Terminated, States...>

Variant type allowing tagged type erased storage of the current state of the FSM.

Definition at line 113 of file FiniteStateMachine.hpp.

View newest version in sPHENIX GitHub at line 113 of file FiniteStateMachine.hpp

Constructor & Destructor Documentation

template<typename Derived, typename... States>
Acts::FiniteStateMachine< Derived, States >::FiniteStateMachine ( )
inline

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

Definition at line 123 of file FiniteStateMachine.hpp.

View newest version in sPHENIX GitHub at line 123 of file FiniteStateMachine.hpp

template<typename Derived, typename... States>
Acts::FiniteStateMachine< Derived, States >::FiniteStateMachine ( StateVariant  state)
inline

Constructor from an explicit state. The FSM is initialized to this state.

Parameters
stateInitial state for the FSM.

Definition at line 129 of file FiniteStateMachine.hpp.

View newest version in sPHENIX GitHub at line 129 of file FiniteStateMachine.hpp

Member Function Documentation

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

Public interface to handle an event. Will call the appropriate event handlers and perform any required transitions.

Template Parameters
EventType of the event being triggered
ArgsAdditional arguments being passed to overload handlers.
Parameters
eventInstance of the event being triggere
argsAdditional arguments

Definition at line 221 of file FiniteStateMachine.hpp.

View newest version in sPHENIX GitHub at line 221 of file FiniteStateMachine.hpp

template<typename Derived, typename... States>
const StateVariant& Acts::FiniteStateMachine< Derived, States >::getState ( ) const
inlinenoexcept

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

Returns
StateVariant The current state of the FSM.

Definition at line 133 of file FiniteStateMachine.hpp.

View newest version in sPHENIX GitHub at line 133 of file FiniteStateMachine.hpp

template<typename Derived, typename... States>
template<typename S >
bool Acts::FiniteStateMachine< Derived, States >::is ( const S ) const
inlinenoexcept

Returns whether the FSM is in the specified state

Template Parameters
Statetype to check against
Parameters
stateState instance to check against
Returns
Whether the FSM is in the given state.

Definition at line 161 of file FiniteStateMachine.hpp.

View newest version in sPHENIX GitHub at line 161 of file FiniteStateMachine.hpp

Referenced by Acts::Test::BOOST_AUTO_TEST_CASE(), ludecy(), luedit(), lujmas(), lustrf(), pybook(), pydecy(), pydocu(), pydump(), pyedit(), pyevol(), pyfact(), pyfill(), pyfscr(), pyhirand(), pyhiremn(), pyhisspa(), pyhist(), pyhistfu(), pyhithia(), pyjmas(), pymihg(), pymihk(), pynull(), pypdpi(), pypdpo(), pyplot(), pyprep(), pyptis(), pyrand(), pyreco(), pyremn(), pysspa(), pystfu(), pystrf(), and pythia().

+ Here is the caller graph for this function:

template<typename Derived, typename... States>
template<typename S >
bool Acts::FiniteStateMachine< Derived, States >::is ( ) const
inlinenoexcept

Returns whether the FSM is in the specified state. Alternative version directly taking only the template argument.

Template Parameters
Statetype to check against
Returns
Whether the FSM is in the given state.

Definition at line 170 of file FiniteStateMachine.hpp.

View newest version in sPHENIX GitHub at line 170 of file FiniteStateMachine.hpp

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

Handles processing of an event.

Note
This should only be called from inside the class Deriving from FSM.
Template Parameters
EventType of the event being processed
ArgsArguments being passed to the overload handlers.
Parameters
eventInstance of the event
argsAdditional arguments
Returns
Variant state type, signifying if a transition is supposed to happen.

Definition at line 191 of file FiniteStateMachine.hpp.

View newest version in sPHENIX GitHub at line 191 of file FiniteStateMachine.hpp

Referenced by Acts::FiniteStateMachine< fsm2, states::Disconnected, states::Connected >::dispatch().

+ Here is the caller graph for this function:

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

Sets the state to a given one. Triggers on_exit and on_enter for the given states.

Template Parameters
StateType of the target state
ArgsAdditional arguments passed through callback overloads.
Parameters
stateInstance of the target state
argsThe additional arguments

Definition at line 143 of file FiniteStateMachine.hpp.

View newest version in sPHENIX GitHub at line 143 of file FiniteStateMachine.hpp

Referenced by Acts::FiniteStateMachine< fsm2, states::Disconnected, states::Connected >::dispatch().

+ Here is the caller graph for this function:

template<typename Derived, typename... States>
bool Acts::FiniteStateMachine< Derived, States >::terminated ( ) const
inlinenoexcept

Returns whether the FSM is in the terminated state.

Returns
Whether the FSM is in the terminated state.

Definition at line 179 of file FiniteStateMachine.hpp.

View newest version in sPHENIX GitHub at line 179 of file FiniteStateMachine.hpp

Member Data Documentation


The documentation for this class was generated from the following file: