libzypp: zyppng::Statemachine< Derived, StateId, Transitions > Class Template Reference

libzypp 17.38.15

zyppng::Statemachine< Derived, StateId, Transitions > Class Template Reference

This defines the actual StateMachine. More...

`#include <zypp-core/ng/base/statemachine.h>`

## Classes
struct | _InitialState

## Public Types
using | AllStates = typename detail::make_state_set< Transitions... >::Type
using | StateSetHelper = typename detail::make_statewithtransition_set< _InitialState, AllStates, Transitions... >
using | FState = typename StateSetHelper::FirstState
using | StateSet = typename StateSetHelper::Type
using | StatemachineType = Statemachine< Derived, StateId, Transitions...>

## Public Member Functions
| Statemachine ()
virtual | ~Statemachine ()
void | start ()
template<typename Func>
auto | visitState (Func &&f)
std::optional< StateId > | currentState () const
std::optional< StateId > | previousState () const
template<typename T>
std::shared_ptr< T > | state ()
template<typename T>
const std::shared_ptr< T > | state () const
template<typename NewState>
void | forceState (std::unique_ptr< NewState > &&nS)
SignalProxy< void()> | sigFinished ()
SignalProxy< void(StateId)> | sigStateChanged ()

## Protected Member Functions
template<typename OldState, typename NewState>
void | enterState (OldState &os, NewState &&nS)
template<typename NewState>
void | enterState (NewState &&nS)
template<typename State, typename Transition>
auto | makeEventCallback (Transition &transition)
template<std::size_t I = 0, typename State, typename ... StateTrans>
void | connectAllTransitions (State &&nS, std::tuple< StateTrans... > &transitions)
void | clearConnections ()

## Private Attributes
bool | _isInFinalState = false
bool | _emittedFinalSig = false
Signal< void(StateId)> | _sigStateChanged
Signal< void()> | _sigFinished
StateSet | _state = _InitialState()
std::optional< StateId > | _previousState
std::vector< sigc::connection > | _currentStateConnections

## Detailed Description

template<typename Derived, typename StateId, typename ... Transitions>
class zyppng::Statemachine< Derived, StateId, Transitions >

This defines the actual StateMachine.

Template Parameters

  Derived | is the Statemachine subclass type, this is used to pass a reference to the actual implementation into the State functions.
  StateId | should be a enum with a ID for each state the SM can be in.
  Transitions | variadic template argument taking a list of all Transition types the statemachine should support. The First Source State in the Transitions List is always the initial state.

Implementation of a simple signal based statemachine, each state is a user defined state type that has to implement a specific API in order to be compatible. No inheritance is required to use the statemachine and everything will be resolved at compile time.

This is how a basic statemachine implementation would look like

// Each state should have a representation in the enum
enum States {
StateA,
StateB,
...
}
class MyStateMachine;
class State;
class StateB;
class StateC;
class StateD;
// states are just simple types with a few required functions, there is a helper class
// SimpleState<> to help with the implementation
class StateA {
// the ID of the state
static constexpr auto stateId = States::StateA;
// is this a final state?
static constexpr bool isFinal = false;
// constructor taking the parent statemachine type
StateA ( MyStateMachine &parent ) {}
// function called when the state is first entered
void enter() {}
// function called when the state is exited
void exit () {}
// a state that is not final needs event sources
SignalProxy<void()> sigTransition ();
// a state might even define a transition function to the target states
std::unique_ptr<StateB> transitionToB ();
// also condition functions can be defined in a state:
bool transitionToStateBCondition() const;
}
// transition functions can also be defined as free functions or static member functions with the signature:
std::unique_ptr<StateC> transitionStateBToStateC ( MyStateMachine &sm, StateB &oldState );
// condition functions can also be defined as free functions or static member functions with the signature:
bool transitionStateAToStateDCondition( State &currentState );
// implementing the statemachine itself, using a template helper for better readability:
template <typename T>
using SmBase = zyppng::Statemachine<T, States,
zyppng::Transition< StateA, &StateA::sigTransition, StateB, &StateA::transitionToStateBCondition, &StateA::transitionToB,
zyppng::Transition< StateB, &StateB::sigTransition, StateC, zyppng::DefaultStateCondition, &transitionStateBToStateC >,
zyppng::Transition< StateB, &StateB::sigTransition, StateD >>;
// by using CRTP we can have a reference to the concrete Statemachine type in the States, allowing us to be much
// more flexible with the implementation, since all states can now access API exported by the MyStateMachine type.
// since the Statemachine uses signals, make sure to derive it also from the \ref zyppng::Base type.
class MyStateMachine : public SmBase<MyStateMachine>, public Base { };
zyppng::Statemachine::currentState
std::optional< StateId > currentState() const
Definition statemachine.h:410

In order to advance the statemachine, each state will have at least one signal ( event ) that tells the statemachine to transition to the next state, optionally a condition can be used to block the transition in certain cases. When transitioning from one state to the other a transition operation will be called that creates the instance of the target state and do other initializations or can move data from the old to the new state. The default version of the operation just returns a new instance of the target state. If a signal or event is used multiple times to trigger transitions, only the first transition whose condition evaluates to true will be triggered. All other transitions with the same trigger signal will not be even evaluated.

After instantiating the statemachine will be in a internal intial state, in order to move to the first user defined state Statemachine::start must be called.

Definition at line 364 of file statemachine.h.

## Member Typedef Documentation

## ◆ AllStates

template<typename Derived, typename StateId, typename ... Transitions>

using zyppng::Statemachine< Derived, StateId, Transitions >::AllStates = typename detail::make_state_set< Transitions... >::Type

Definition at line 370 of file statemachine.h.

## ◆ StateSetHelper

template<typename Derived, typename StateId, typename ... Transitions>

using zyppng::Statemachine< Derived, StateId, Transitions >::StateSetHelper = typename detail::make_statewithtransition_set< _InitialState, AllStates, Transitions... >

Definition at line 371 of file statemachine.h.

## ◆ FState

template<typename Derived, typename StateId, typename ... Transitions>

using zyppng::Statemachine< Derived, StateId, Transitions >::FState = typename StateSetHelper::FirstState

Definition at line 372 of file statemachine.h.

## ◆ StateSet

template<typename Derived, typename StateId, typename ... Transitions>

using zyppng::Statemachine< Derived, StateId, Transitions >::StateSet = typename StateSetHelper::Type

Definition at line 373 of file statemachine.h.

## ◆ StatemachineType

template<typename Derived, typename StateId, typename ... Transitions>

using zyppng::Statemachine< Derived, StateId, Transitions >::StatemachineType = Statemachine< Derived, StateId, Transitions...>

Definition at line 375 of file statemachine.h.

## Constructor & Destructor Documentation

## ◆ Statemachine()

template<typename Derived, typename StateId, typename ... Transitions>

zyppng::Statemachine< Derived, StateId, Transitions >::Statemachine | ( |  | ) |
| inline

Definition at line 378 of file statemachine.h.

## ◆ ~Statemachine()

template<typename Derived, typename StateId, typename ... Transitions>

virtual zyppng::Statemachine< Derived, StateId, Transitions >::~Statemachine | ( |  | ) |
| inlinevirtual

Definition at line 379 of file statemachine.h.

## Member Function Documentation

## ◆ start()

template<typename Derived, typename StateId, typename ... Transitions>

void zyppng::Statemachine< Derived, StateId, Transitions >::start | ( |  | ) |
| inline

Advances the state machine into the initial state.

Definition at line 384 of file statemachine.h.

## ◆ visitState()

template<typename Derived, typename StateId, typename ... Transitions>
template<typename Func>

auto zyppng::Statemachine< Derived, StateId, Transitions >::visitState | ( | Func && | f | ) |
| inline

Definition at line 394 of file statemachine.h.

## ◆ currentState()

template<typename Derived, typename StateId, typename ... Transitions>

std::optional< StateId > zyppng::Statemachine< Derived, StateId, Transitions >::currentState | ( |  | ) | const
| inline

Returns the current stateId of the state the SM is currently in. If called before start() was called the std::optional will be empty

Definition at line 410 of file statemachine.h.

## ◆ previousState()

template<typename Derived, typename StateId, typename ... Transitions>

std::optional< StateId > zyppng::Statemachine< Derived, StateId, Transitions >::previousState | ( |  | ) | const
| inline

Returns the ID of the previous state, or a invalid optional if there was no previous state.

Definition at line 425 of file statemachine.h.

## ◆ state() [1/2]

template<typename Derived, typename StateId, typename ... Transitions>
template<typename T>

std::shared_ptr< T > zyppng::Statemachine< Derived, StateId, Transitions >::state | ( |  | ) |
| inline

Returns a reference to the current state object, will throw a exception if the passed state type does not match the current states type.

Definition at line 434 of file statemachine.h.

## ◆ state() [2/2]

template<typename Derived, typename StateId, typename ... Transitions>
template<typename T>

const std::shared_ptr< T > zyppng::Statemachine< Derived, StateId, Transitions >::state | ( |  | ) | const
| inline

Returns a reference to the current state object, will throw a exception if the passed state type does not match the current states type.

Definition at line 444 of file statemachine.h.

## ◆ forceState()

template<typename Derived, typename StateId, typename ... Transitions>
template<typename NewState>

void zyppng::Statemachine< Derived, StateId, Transitions >::forceState | ( | std::unique_ptr< NewState > && | nS | ) |
| inline

Forces the statemachine to enter a specific state, a transition operation will not be executed, but the exit() function of the current state will be called.

Definition at line 454 of file statemachine.h.

## ◆ sigFinished()

template<typename Derived, typename StateId, typename ... Transitions>

SignalProxy< void()> zyppng::Statemachine< Derived, StateId, Transitions >::sigFinished | ( |  | ) |
| inline

Emitted when the statemachine enters a type that has final set to true.

Definition at line 471 of file statemachine.h.

## ◆ sigStateChanged()

template<typename Derived, typename StateId, typename ... Transitions>

SignalProxy< void(StateId)> zyppng::Statemachine< Derived, StateId, Transitions >::sigStateChanged | ( |  | ) |
| inline

Emitted everytime the statemachine advanced to a new state, carrying the new state's ID.

Note
  this signal is emitted before State::enter() is executed, the State object however is already created and can be accessed via Statemachine::state()

Definition at line 481 of file statemachine.h.

## ◆ enterState() [1/2]

template<typename Derived, typename StateId, typename ... Transitions>
template<typename OldState, typename NewState>

void zyppng::Statemachine< Derived, StateId, Transitions >::enterState | ( | OldState & | os,
|  | NewState && | nS )
| inlineprotected

Definition at line 488 of file statemachine.h.

## ◆ enterState() [2/2]

template<typename Derived, typename StateId, typename ... Transitions>
template<typename NewState>

void zyppng::Statemachine< Derived, StateId, Transitions >::enterState | ( | NewState && | nS | ) |
| inlineprotected

Definition at line 497 of file statemachine.h.

## ◆ makeEventCallback()

template<typename Derived, typename StateId, typename ... Transitions>
template<typename State, typename Transition>

auto zyppng::Statemachine< Derived, StateId, Transitions >::makeEventCallback | ( | Transition & | transition | ) |
| inlineprotected

Definition at line 526 of file statemachine.h.

## ◆ connectAllTransitions()

template<typename Derived, typename StateId, typename ... Transitions>
template<std::size_t I = 0, typename State, typename ... StateTrans>

void zyppng::Statemachine< Derived, StateId, Transitions >::connectAllTransitions | ( | State && | nS,
|  | std::tuple< StateTrans... > & | transitions )
| inlineprotected

Definition at line 538 of file statemachine.h.

## ◆ clearConnections()

template<typename Derived, typename StateId, typename ... Transitions>

void zyppng::Statemachine< Derived, StateId, Transitions >::clearConnections | ( |  | ) |
| inlineprotected

Definition at line 549 of file statemachine.h.

## Member Data Documentation

## ◆ _isInFinalState

template<typename Derived, typename StateId, typename ... Transitions>

bool zyppng::Statemachine< Derived, StateId, Transitions >::_isInFinalState = false
| private

Definition at line 556 of file statemachine.h.

## ◆ _emittedFinalSig

template<typename Derived, typename StateId, typename ... Transitions>

bool zyppng::Statemachine< Derived, StateId, Transitions >::_emittedFinalSig = false
| private

Definition at line 557 of file statemachine.h.

## ◆ _sigStateChanged

template<typename Derived, typename StateId, typename ... Transitions>

Signal<void ( StateId )> zyppng::Statemachine< Derived, StateId, Transitions >::_sigStateChanged
| private

Definition at line 558 of file statemachine.h.

## ◆ _sigFinished

template<typename Derived, typename StateId, typename ... Transitions>

Signal<void ()> zyppng::Statemachine< Derived, StateId, Transitions >::_sigFinished
| private

Definition at line 559 of file statemachine.h.

## ◆ _state

template<typename Derived, typename StateId, typename ... Transitions>

StateSet zyppng::Statemachine< Derived, StateId, Transitions >::_state = _InitialState()
| private

Definition at line 560 of file statemachine.h.

## ◆ _previousState

template<typename Derived, typename StateId, typename ... Transitions>

std::optional<StateId> zyppng::Statemachine< Derived, StateId, Transitions >::_previousState
| private

Definition at line 561 of file statemachine.h.

## ◆ _currentStateConnections

template<typename Derived, typename StateId, typename ... Transitions>

std::vector<sigc::connection> zyppng::Statemachine< Derived, StateId, Transitions >::_currentStateConnections
| private

Definition at line 562 of file statemachine.h.

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

- zypp-core/ng/base/statemachine.h