State Machine
Tools for creating and running general purpose state machines.
state_machine::Concurrency Class Reference

#include <Concurrency.hpp>

Inheritance diagram for state_machine::Concurrency:
Inheritance graph

Classes

struct  PreemptImmediately
 
struct  PreemptNever
 

Public Types

using StateOutcomes = std::map< std::string, std::string >
 
using StateOutcomeMapping = std::vector< std::pair< StateOutcomes, std::string > >
 
using ChildTerminationCallback = std::function< bool(const StateOutcomes &)>
 
using TerminationCallback = std::function< std::string(const StateOutcomes &)>
 

Public Member Functions

 Concurrency (ContextPtr context, std::string name, std::set< std::string > outcomes, std::string defaultOutcome, StateOutcomeMapping stateOutcomeMapping={}, ChildTerminationCallback childTerminationCb={}, TerminationCallback terminationCb={})
 
 ~Concurrency () override=default
 
const std::string & getDefaultOutcome () const
 
const StateOutcomeMappinggetStateOutcomeMapping () const
 
void addState (const StatePtr &state, bool isBackgroundState=false)
 
void removeStateByName (const std::string &name) override
 
void clear () override
 
void getAvailableInitialStateNestedNames (std::set< NestedName > &nestedNames) const override
 
bool setInitialStateByNestedName (const NestedName &nestedName) override
 
bool isConsistent (std::vector< std::string > &inconsistencies) const override
 
std::string midExecution () override
 
bool requestPauseAfterExecution () override
 
std::map< NestedName, ProgressgetRunningStates (const bool ignoreBackgroundStates) override
 
- Public Member Functions inherited from state_machine::Container
void addState (const StatePtr &state)
 
bool stateExists (const std::string &name) const
 
StatePtr getState (const std::string &name)
 
std::map< std::string, StatePtrgetStates () const
 
std::set< std::string > getStateNames () const
 
bool isConsistent (std::vector< std::string > &inconsistencies) const override
 
void recallPauseAfterExecution () override
 
bool pauseAfterExecutionRequested () override
 
void requestPreempt () override
 
void recallPreempt () override
 
void printStateHierarchy (const bool useNestedNames, const bool useIndentation, const unsigned int indentation) const override
 
- Public Member Functions inherited from state_machine::State
 State (ContextPtr context, std::string name, std::set< std::string > outcomes)
 
virtual ~State ()=default
 
ContextPtr getContext () const
 
void setName (const std::string &name)
 
const std::string & getName () const
 
NestedName getNestedName () const
 
const std::set< std::string > & getOutcomes () const
 
const std::string & getType () const
 
void resetIds ()
 
const std::string & getKeyPrefix () const
 
void setParent (State *parent)
 
StategetParent ()
 
void resetParent ()
 
virtual void loadSettings (const Settings &settings)
 
virtual void saveSettings (Settings &settings) const
 
std::string execute ()
 
bool isRunning () const
 
void requestPause ()
 
void requestResume ()
 
bool isPaused ()
 
void servicePreempt ()
 
bool preemptRequested () const
 
void sleepOnce ()
 
void sleepWhilePaused ()
 
virtual Progress getProgress ()
 
void printStateHierarchy ()
 

Protected Member Functions

void executeState (StatePtr state)
 
- Protected Member Functions inherited from state_machine::Container
 Container (ContextPtr context, std::string name, std::set< std::string > outcomes)
 
 ~Container () override=default
 
- Protected Member Functions inherited from state_machine::State
void setId ()
 
virtual void preExecution ()
 
virtual void postExecution ()
 
void sleep (const double duration)
 

Protected Attributes

std::string defaultOutcome_
 
StateOutcomeMapping stateOutcomeMapping_
 
ChildTerminationCallback childTerminationCb_
 
TerminationCallback terminationCb_
 
std::map< std::string, bool > isBackgroundState_
 
std::mutex stateOutcomesMutex_
 
StateOutcomes stateOutcomes_
 
- Protected Attributes inherited from state_machine::Container
std::map< std::string, StatePtrstates_
 
- Protected Attributes inherited from state_machine::State
ContextPtr context_
 
std::string name_
 
std::string type_
 
std::set< std::string > outcomes_
 
unsigned int id_ = -1
 
std::string keyPrefix_
 
Stateparent_ = nullptr
 
std::atomic< bool > isRunning_
 
std::atomic< bool > preemptRequested_
 
Progress progress_
 

Additional Inherited Members

- Static Public Member Functions inherited from state_machine::State
static double getTimeStep ()
 
- Static Protected Attributes inherited from state_machine::State
static std::mutex freeIdMutex_
 
static int freeId_ = 0
 
static double timeStep_ = 0.1
 
static std::atomic< bool > isPaused_
 

Detailed Description

A concurrency is a state which runs child states in parallel.

The states are started simultaneously when the concurrency is started. Each of the states is run in its own thread, while the main thread is waiting for the states to finish.

If one of the concurrent states is finished, the child termination callback is called to determine whether the still running states should be preempted.

As soon as all states are finished or preempted, the outcome of the concurrency is determined in the following hierarchy:

  1. If set, call the termination callback. In this callback the user can process the outcomes of the states and return an outcome.
  2. Check the state outcome mapping. The first condition which is fulfilled determines the outcome.
  3. If none of the conditions is fulfilled, return the default outcome.

Member Typedef Documentation

◆ ChildTerminationCallback

Child termination callback. Receives the outcomes of the child states which have already finished, returns true if the still running states should be preempted, false to let them continue.

◆ StateOutcomeMapping

using state_machine::Concurrency::StateOutcomeMapping = std::vector<std::pair<StateOutcomes, std::string> >

Mapping from the outcomes of the child states to the outcome of the concurrency. The first element in the mapping which matches the actual outcomes of the child states determines the outcome of the concurreny.

◆ StateOutcomes

using state_machine::Concurrency::StateOutcomes = std::map<std::string, std::string>

Outcomes of the child states. Map from child state name to child state outcome.

◆ TerminationCallback

using state_machine::Concurrency::TerminationCallback = std::function<std::string(const StateOutcomes&)>

Termination callback when all child states have finished. Receives the outcomes of the child states which have already finished and returns the outcome of the concurrency.

Constructor & Destructor Documentation

◆ Concurrency()

state_machine::Concurrency::Concurrency ( ContextPtr  context,
std::string  name,
std::set< std::string >  outcomes,
std::string  defaultOutcome,
StateOutcomeMapping  stateOutcomeMapping = {},
ChildTerminationCallback  childTerminationCb = {},
TerminationCallback  terminationCb = {} 
)

General methods. Constructor.

Parameters
contextShared state machine context.
nameName of the concurrency.
outcomesList of possible outcomes.
defaultOutcomeDefault outcome of the concurrecny.
stateOutcomeMappingMapping of the outcomes of the child states to the outcome of the concurrency.
childTerminationCbCallback function which is called whenever a child state has finished.
terminationCbCallback function which is called as soon as all child states have finished or have been preempted.

◆ ~Concurrency()

state_machine::Concurrency::~Concurrency ( )
overridedefault

Destructor.

Member Function Documentation

◆ addState()

void state_machine::Concurrency::addState ( const StatePtr state,
bool  isBackgroundState = false 
)

Setup methods. Add a child state to the concurrency.

Parameters
stateState to add.
isBackgroundStateIndicate whether the state is a background state or not.

◆ clear()

void state_machine::Concurrency::clear ( )
overridevirtual

Clear the concurrency, removing all contained child states.

Reimplemented from state_machine::Container.

◆ executeState()

void state_machine::Concurrency::executeState ( StatePtr  state)
protected

Execute a single child state.

Parameters
stateChild state.

◆ getAvailableInitialStateNestedNames()

void state_machine::Concurrency::getAvailableInitialStateNestedNames ( std::set< NestedName > &  nestedNames) const
overridevirtual

Get the available initial states of the contained child states. Note that the concurrency itself does not have an initial state.

Parameters
nestedNamesReturn argument, will contain the nested names of the available initial states.

Reimplemented from state_machine::State.

◆ getDefaultOutcome()

const std::string & state_machine::Concurrency::getDefaultOutcome ( ) const

Get the default outcome.

Returns
Default outcome.

◆ getRunningStates()

std::map< NestedName, Progress > state_machine::Concurrency::getRunningStates ( const bool  ignoreBackgroundStates)
overridevirtual

Get a list of the running states and their progresses.

Parameters
ignoreBackgroundStatesIf true, the list will not contain background states.
Returns
List of the nested names of the states and their progresses.

Reimplemented from state_machine::State.

◆ getStateOutcomeMapping()

const Concurrency::StateOutcomeMapping & state_machine::Concurrency::getStateOutcomeMapping ( ) const

Get the mapping of the child state outcomes.

Returns
Mapping of the child state outcomes.

◆ isConsistent()

bool state_machine::Concurrency::isConsistent ( std::vector< std::string > &  inconsistencies) const
overridevirtual

Check if the concurrency is consistent.

Parameters
inconsistenciesReturn argument, will contain a list of inconsistencies for printing.
Returns
True if consistent.

Reimplemented from state_machine::State.

◆ midExecution()

std::string state_machine::Concurrency::midExecution ( )
overridevirtual

Execution methods. Mid-execution of the concurrency.

Returns
Outcome of the execution.

Implements state_machine::State.

◆ removeStateByName()

void state_machine::Concurrency::removeStateByName ( const std::string &  name)
overridevirtual

Remove a child state from the concurrency.

Parameters
nameName of the child state to remove.

Reimplemented from state_machine::Container.

◆ requestPauseAfterExecution()

bool state_machine::Concurrency::requestPauseAfterExecution ( )
overridevirtual

Request to pause after executing the currently running state.

Returns
True if successful.

Reimplemented from state_machine::State.

◆ setInitialStateByNestedName()

bool state_machine::Concurrency::setInitialStateByNestedName ( const NestedName nestedName)
overridevirtual

Set the initial state of the contained child states.

Parameters
nestedNameNested name of the initial state.
Returns
True if successful.

Reimplemented from state_machine::State.

Member Data Documentation

◆ childTerminationCb_

ChildTerminationCallback state_machine::Concurrency::childTerminationCb_
protected

◆ defaultOutcome_

std::string state_machine::Concurrency::defaultOutcome_
protected

Members set during setup.

◆ isBackgroundState_

std::map<std::string, bool> state_machine::Concurrency::isBackgroundState_
protected

◆ stateOutcomeMapping_

StateOutcomeMapping state_machine::Concurrency::stateOutcomeMapping_
protected

◆ stateOutcomes_

StateOutcomes state_machine::Concurrency::stateOutcomes_
protected

◆ stateOutcomesMutex_

std::mutex state_machine::Concurrency::stateOutcomesMutex_
protected

Members set during execution.

◆ terminationCb_

TerminationCallback state_machine::Concurrency::terminationCb_
protected

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