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


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.

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


Member Function Documentation

◆ addState()

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

Setup methods. Add a child state to the concurrency.

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

◆ clear()

void state_machine::Concurrency::clear ( )

Clear the concurrency, removing all contained child states.

Reimplemented from state_machine::Container.

◆ executeState()

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

Execute a single child state.

stateChild state.

◆ getAvailableInitialStateNestedNames()

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

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

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.

Default outcome.

◆ getRunningStates()

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

Get a list of the running states and their progresses.

ignoreBackgroundStatesIf true, the list will not contain background states.
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.

Mapping of the child state outcomes.

◆ isConsistent()

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

Check if the concurrency is consistent.

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

Reimplemented from state_machine::State.

◆ midExecution()

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

Execution methods. Mid-execution of the concurrency.

Outcome of the execution.

Implements state_machine::State.

◆ removeStateByName()

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

Remove a child state from the concurrency.

nameName of the child state to remove.

Reimplemented from state_machine::Container.

◆ requestPauseAfterExecution()

bool state_machine::Concurrency::requestPauseAfterExecution ( )

Request to pause after executing the currently running state.

True if successful.

Reimplemented from state_machine::State.

◆ setInitialStateByNestedName()

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

Set the initial state of the contained child states.

nestedNameNested name of the initial state.
True if successful.

Reimplemented from state_machine::State.

Member Data Documentation

◆ childTerminationCb_

ChildTerminationCallback state_machine::Concurrency::childTerminationCb_

◆ defaultOutcome_

std::string state_machine::Concurrency::defaultOutcome_

Members set during setup.

◆ isBackgroundState_

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

◆ stateOutcomeMapping_

StateOutcomeMapping state_machine::Concurrency::stateOutcomeMapping_

◆ stateOutcomes_

StateOutcomes state_machine::Concurrency::stateOutcomes_

◆ stateOutcomesMutex_

std::mutex state_machine::Concurrency::stateOutcomesMutex_

Members set during execution.

◆ terminationCb_

TerminationCallback state_machine::Concurrency::terminationCb_

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