yasmin::StateMachine Class Reference

A class that implements a state machine with a set of states, transitions, and callback mechanisms for state changes. More...

#include <state_machine.hpp>

Inheritance diagram for yasmin::StateMachine:

Collaboration diagram for yasmin::StateMachine:

Public Types
using	StartCallbackType
	Alias for a callback function executed before running the state machine.
using	TransitionCallbackType
	Alias for a callback function executed before changing the state.
using	EndCallbackType
	Alias for a callback function executed after running the state machine.

Public Member Functions
	StateMachine (const Outcomes &outcomes, bool handle_sigint=false)
	Shared pointer type for StateMachine.
	StateMachine (const std::string &name, const Outcomes &outcomes, bool handle_sigint=false)
	Construct a new StateMachine object.
	~StateMachine ()
	Destroy the StateMachine object.
void	add_state (const std::string &name, State::SharedPtr state, const Transitions &transitions={}, const Remappings &remappings={})
	Adds a state to the state machine with specified transitions.
void	set_name (const std::string &name)
	Sets the name of the state machine.
const std::string &	get_name () const noexcept
	Gets the name of the state machine.
void	set_start_state (const std::string &state_name)
	Sets the start state for the state machine.
std::string const &	get_start_state () const noexcept
	Retrieves the name of the start state.
StateMap const &	get_states () const noexcept
	Gets a constant reference to the map of states.
TransitionsMap const &	get_transitions () const noexcept
	Gets a constant reference to the map of transitions.
std::string const &	get_current_state () const
	Retrieves the current state name.
void	add_start_cb (StartCallbackType cb)
	Adds a callback function to be called when the state machine starts.
void	add_transition_cb (TransitionCallbackType cb)
	Adds a callback function for state transitions.
void	add_end_cb (EndCallbackType cb)
	Adds a callback function to be called when the state machine ends.
void	validate (bool strict_mode=false)
	Validates the state machine configuration.
std::string	execute (Blackboard::SharedPtr blackboard) override
	Executes the state machine.
std::string	execute ()
	Executes the state machine using a default blackboard.
std::string	operator() ()
	Invokes the state machine using a default blackboard.
void	cancel_state () override
	Cancels the current state execution.
void	set_sigint_handler (bool handle=true)
	Sets whether the state machine should handle SIGINT for cancel.
std::string	to_string () const override
	Converts the state machine to a string representation.
std::string	operator() (Blackboard::SharedPtr blackboard)
	Executes the state and returns the outcome.
Public Member Functions inherited from yasmin::State
	State (const Outcomes &outcomes)
	Shared pointer type for State.
virtual	~State ()=default
	Virtual destructor for proper polymorphic destruction.
bool	is_idle () const noexcept
	Checks if the state is idle.
bool	is_running () const noexcept
	Checks if the state is currently running.
bool	is_canceled () const noexcept
	Checks if the state has been canceled.
bool	is_completed () const noexcept
	Checks if the state has completed execution.
std::string	operator() (Blackboard::SharedPtr blackboard)
	Executes the state and returns the outcome.
Outcomes const &	get_outcomes () const noexcept
	Gets the set of possible outcomes for this state.

Private Member Functions
void	set_current_state (const std::string &state_name)
	Sets the current state name.
void	call_start_cbs (Blackboard::SharedPtr blackboard, const std::string &start_state)
	Calls start callbacks with the given blackboard and start state.
void	call_transition_cbs (Blackboard::SharedPtr blackboard, const std::string &from_state, const std::string &to_state, const std::string &outcome)
	Calls transition callbacks when transitioning between states.
void	call_end_cbs (Blackboard::SharedPtr blackboard, const std::string &outcome)
	Calls end callbacks with the given blackboard and outcome.

Private Attributes
std::string	name
StateMap	states
	Map of states.
TransitionsMap	transitions
	Map of transitions.
RemappingsMap	remappings
	A dictionary of remappings to set in the blackboard in each transition.
std::string	start_state
	Name of the start state.
std::string	current_state
	Name of the current state.
std::unique_ptr< std::mutex >	current_state_mutex
	Mutex for current state access.
std::condition_variable	current_state_cond
	Condition variable for current state changes.
std::atomic_bool	validated {false}
	Flag to indicate if the state machine has been validated.
std::vector< StartCallbackType >	start_cbs
	Start callbacks executed before the state machine.
std::vector< TransitionCallbackType >	transition_cbs
	Transition callbacks executed before changing the state.
std::vector< EndCallbackType >	end_cbs
	End callbacks executed before the state machine.

Additional Inherited Members
Protected Attributes inherited from yasmin::State
Outcomes	outcomes
	The possible outcomes of this state.

Detailed Description

A class that implements a state machine with a set of states, transitions, and callback mechanisms for state changes.

The StateMachine class inherits from the State class and allows the registration of states with their respective transitions and callbacks for start, transition, and end events.

Member Typedef Documentation

EndCallbackType

using yasmin::StateMachine::EndCallbackType

Initial value:

 
      std::function<void(Blackboard::SharedPtr, const std::string &)>

Alias for a callback function executed after running the state machine.

StartCallbackType

using yasmin::StateMachine::StartCallbackType

Initial value:

 
      std::function<void(Blackboard::SharedPtr, const std::string &)>

Alias for a callback function executed before running the state machine.

TransitionCallbackType

using yasmin::StateMachine::TransitionCallbackType

Initial value:

 
      std::function<void(Blackboard::SharedPtr, const std::string &,
                         const std::string &, const std::string &)>

Alias for a callback function executed before changing the state.

Constructor & Destructor Documentation

StateMachine() [1/2]

StateMachine::StateMachine	(	const Outcomes &	outcomes,
		bool	handle_sigint = false )

Shared pointer type for StateMachine.

Construct a new StateMachine object.

Parameters

outcomes	A set of possible outcomes for the state machine.
handle_sigint	Whether to handle SIGINT for canceling the state machine.

StateMachine() [2/2]

StateMachine::StateMachine	(	const std::string &	name,
		const Outcomes &	outcomes,
		bool	handle_sigint = false )

Construct a new StateMachine object.

Parameters

name	The name of the state machine.
outcomes	A set of possible outcomes for the state machine.
handle_sigint	Whether to handle SIGINT for canceling the state machine.

~StateMachine()

StateMachine::~StateMachine

(

)

Destroy the StateMachine object.

Member Function Documentation

add_end_cb()

void StateMachine::add_end_cb

(

EndCallbackType

cb

)

Adds a callback function to be called when the state machine ends.

Parameters

cb	The callback function to execute.

add_start_cb()

void StateMachine::add_start_cb

(

StartCallbackType

cb

)

Adds a callback function to be called when the state machine starts.

Parameters

cb	The callback function to execute.

add_state()

void StateMachine::add_state	(	const std::string &	name,
		State::SharedPtr	state,
		const Transitions &	transitions = {},
		const Remappings &	remappings = {} )

Adds a state to the state machine with specified transitions.

Parameters

name	The name of the state.
state	A shared pointer to the State object representing the new state.
transitions	A map of transitions where the key is the outcome and the value is the target state name.
remappings	A map of remappings keys for the blackboard.

Exceptions

std::logic_error	If the state is already registered or is an outcome.
std::invalid_argument	If any transition has empty source or target, or references unregistered outcomes.

add_transition_cb()

void StateMachine::add_transition_cb

(

TransitionCallbackType

cb

)

Adds a callback function for state transitions.

Parameters

cb	The callback function to execute.

call_end_cbs()

void StateMachine::call_end_cbs ( Blackboard::SharedPtr blackboard, const std::string & outcome )

private

Calls end callbacks with the given blackboard and outcome.

Parameters

blackboard	A shared pointer to the blackboard.
outcome	The outcome when the state machine ends.

call_start_cbs()

void StateMachine::call_start_cbs ( Blackboard::SharedPtr blackboard, const std::string & start_state )

private

Calls start callbacks with the given blackboard and start state.

Parameters

blackboard	A shared pointer to the blackboard.
start_state	The name of the start state.

call_transition_cbs()

void StateMachine::call_transition_cbs ( Blackboard::SharedPtr blackboard, const std::string & from_state, const std::string & to_state, const std::string & outcome )

private

Calls transition callbacks when transitioning between states.

Parameters

blackboard	A shared pointer to the blackboard.
from_state	The state being transitioned from.
to_state	The state being transitioned to.
outcome	The outcome that triggered the transition.

cancel_state()

void StateMachine::cancel_state ( )

overridevirtual

Cancels the current state execution.

Reimplemented from yasmin::State.

execute() [1/2]

std::string StateMachine::execute

(

)

Executes the state machine using a default blackboard.

Returns

The outcome of the state machine execution.

execute() [2/2]

std::string StateMachine::execute ( Blackboard::SharedPtr blackboard )

overridevirtual

Executes the state machine.

Parameters

blackboard

A shared pointer to the blackboard used during execution.

Returns

The outcome of the state machine execution.

Exceptions

std::runtime_error

If the execution cannot be completed due to invalid states or transitions.

Reimplemented from yasmin::State.

get_current_state()

std::string const & StateMachine::get_current_state

(

)

const

Retrieves the current state name.

Returns

The name of the current state.

get_name()

const std::string & yasmin::StateMachine::get_name ( ) const

inlinenoexcept

Gets the name of the state machine.

Returns

The name of the state machine.

get_start_state()

std::string const & StateMachine::get_start_state ( ) const

noexcept

Retrieves the name of the start state.

Returns

The name of the start state.

get_states()

StateMap const & StateMachine::get_states ( ) const

noexcept

Gets a constant reference to the map of states.

Returns

A constant reference to the map of states.

get_transitions()

TransitionsMap const & StateMachine::get_transitions ( ) const

noexcept

Gets a constant reference to the map of transitions.

Returns

A constant reference to the map of transitions.

operator()() [1/2]

std::string StateMachine::operator()

(

)

Invokes the state machine using a default blackboard.

Returns

The outcome of the state machine execution.

operator()() [2/2]

std::string State::operator()

(

Blackboard::SharedPtr

blackboard

)

Executes the state and returns the outcome.

Parameters

blackboard

A shared pointer to the Blackboard to use during execution.

Returns

A string representing the outcome of the execution.

This function stores the state as running, invokes the execute method, and checks if the returned outcome is valid. If the outcome is not valid, a std::logic_error is thrown.

Exceptions

std::logic_error

If the outcome is not in the set of outcomes.

set_current_state()

void StateMachine::set_current_state ( const std::string & state_name )

private

Sets the current state name.

Parameters

state_name

The name of the state to set as the current state.

set_name()

void yasmin::StateMachine::set_name ( const std::string & name )

inline

Sets the name of the state machine.

Parameters

name	The name to set for the state machine.

set_sigint_handler()

void StateMachine::set_sigint_handler

(

bool

handle = true

)

Sets whether the state machine should handle SIGINT for cancel.

Parameters

handle

True to handle SIGINT, false to ignore or reset the handler.

set_start_state()

void StateMachine::set_start_state

(

const std::string &

state_name

)

Sets the start state for the state machine.

Parameters

state_name

The name of the state to set as the start state.

Exceptions

std::invalid_argument

If the state name is empty or not registered.

to_string()

std::string StateMachine::to_string ( ) const

overridevirtual

Converts the state machine to a string representation.

Returns

A string describing the state machine and its states.

Reimplemented from yasmin::State.

validate()

void StateMachine::validate

(

bool

strict_mode = false

)

Validates the state machine configuration.

Parameters

strict

Whether the validation is strict, which means checking if all state outcomes are used and all state machine outcomes are reached.

Exceptions

std::runtime_error

If the state machine is misconfigured.

Member Data Documentation

current_state

std::string yasmin::StateMachine::current_state

private

Name of the current state.

current_state_cond

std::condition_variable yasmin::StateMachine::current_state_cond

private

Condition variable for current state changes.

current_state_mutex

std::unique_ptr<std::mutex> yasmin::StateMachine::current_state_mutex

private

Mutex for current state access.

end_cbs

std::vector<EndCallbackType> yasmin::StateMachine::end_cbs

private

End callbacks executed before the state machine.

name

std::string yasmin::StateMachine::name

private

remappings

RemappingsMap yasmin::StateMachine::remappings

private

A dictionary of remappings to set in the blackboard in each transition.

start_cbs

std::vector<StartCallbackType> yasmin::StateMachine::start_cbs

private

Start callbacks executed before the state machine.

start_state

std::string yasmin::StateMachine::start_state

private

Name of the start state.

states

StateMap yasmin::StateMachine::states

private

Map of states.

transition_cbs

std::vector<TransitionCallbackType> yasmin::StateMachine::transition_cbs

private

Transition callbacks executed before changing the state.

transitions

TransitionsMap yasmin::StateMachine::transitions

private

Map of transitions.

validated

std::atomic_bool yasmin::StateMachine::validated {false}

private

Flag to indicate if the state machine has been validated.

---

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

• yasmin/include/yasmin/state_machine.hpp
• yasmin/src/yasmin/state_machine.cpp