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:

[legend]

Collaboration diagram for yasmin::StateMachine:

[legend]

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={}, const ParameterMappings &parameter_mappings={})
	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	set_parameter_mappings (const std::string &state_name, const ParameterMappings &parameter_mappings)
	Sets parameter mappings for a child state.
const ParameterMappingsMap &	get_parameter_mappings () const noexcept
	Gets all parameter mappings.
void	validate (bool strict_mode=false)
	Validates the state machine configuration.
void	configure () override
	Executes the state machine.
std::string	execute (Blackboard::SharedPtr blackboard) override
	Executes the state's specific logic.
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 currently active child state.
void	cancel_state_machine ()
	Cancels the complete state machine 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 ()
	Virtual destructor.
Blackboard::SharedPtr	get_parameters_blackboard () const
	Gets the private parameter blackboard of this state.
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.
void	set_description (const std::string &description)
	Sets the description for this state.
const std::string &	get_description () const
	Gets the description of this state.
void	set_outcome_description (const std::string &outcome, const std::string &description)
	Sets a human-readable description for an outcome.
const std::string &	get_outcome_description (const std::string &outcome) const
	Gets the human-readable description for an outcome.
const std::unordered_map< std::string, std::string > &	get_outcome_descriptions () const
	Gets all outcome descriptions.
void	add_input_key (const BlackboardKeyInfo &key_info)
	Adds an input key to the state's metadata.
void	add_input_key (const std::string &key_name)
	Adds an input key with a name only.
void	add_input_key (const std::string &key_name, const std::string &description)
	Adds an input key with a name and description.
template<typename T>
void	add_input_key (const std::string &key_name, const std::string &description, T default_value)
	Adds an input key with a name, default value and description.
void	add_output_key (const BlackboardKeyInfo &key_info)
	Adds an output key to the state's metadata.
void	add_output_key (const std::string &key_name)
	Adds an output key with a name only.
void	add_output_key (const std::string &key_name, const std::string &description)
	Adds an output key with a name and description.
const std::vector< BlackboardKeyInfo > &	get_input_keys () const
	Gets the input keys metadata.
const std::vector< BlackboardKeyInfo > &	get_output_keys () const
	Gets the output keys metadata.
void	declare_parameter (const BlackboardKeyInfo &parameter_info)
	Declares a parameter in the state metadata.
void	declare_parameter (const std::string &parameter_name)
	Declares a parameter with a name only.
void	declare_parameter (const std::string &parameter_name, const std::string &description)
	Declares a parameter with a name and description.
template<typename T>
void	declare_parameter (const std::string &parameter_name, const std::string &description, T default_value)
	Declares a parameter with a name, description, and default value.
bool	has_parameter (const std::string &parameter_name) const
	Checks if a parameter exists in the state-local parameter storage.
template<typename T>
T	get_parameter (const std::string &parameter_name) const
	Gets a parameter from the state-local parameter storage.
template<typename T>
void	set_parameter (const std::string &parameter_name, T value)
	Sets a parameter in the state-local parameter storage.
bool	is_parameter_declared (const std::string &parameter_name) const
	Checks whether a parameter was declared in the state metadata.
void	copy_parameter_from (const State &source_state, const std::string &source_parameter_name, const std::string &target_parameter_name)
	Copies a parameter value from another state.
const std::vector< BlackboardKeyInfo > &	get_parameters () const
	Gets the declared parameter metadata.
const StateMetadata &	get_metadata () const
	Gets the complete state metadata.

Private Member Functions
void	set_current_state (const std::string &state_name)
	Sets the current state name.
void	apply_parameter_mappings (const std::string &state_name, const State::SharedPtr &state)
	Applies this container's parameter mappings to a direct child.
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.
std::string	wait_for_current_state ()
	Waits until a current state is available while execution is active.
void	throw_if_cancel_state_machine_requested ()
	Throws if a hard state machine cancel was requested.

Static Private Member Functions
static Remappings	compose_remappings (const Remappings &parent_remappings, const Remappings &state_remappings)
	Compose parent and state blackboard remappings.

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.
ParameterMappingsMap	parameter_mappings
	Per-child parameter mappings applied during configure().
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::atomic_bool	configured {false}
	Flag to indicate if the state machine has been configured.
std::atomic_bool	execution_active {false}
	Flag to indicate whether the execute loop is currently active.
std::atomic_bool	cancel_state_machine_requested {false}
	Flag to indicate that a hard state machine cancel was requested.
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 &)>

yasmin::Blackboard::SharedPtr

std::shared_ptr< Blackboard > SharedPtr

Shared pointer type for Blackboard.

Definition blackboard.hpp:100

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 = {},
		const ParameterMappings &	parameter_mappings = {} )

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.

◆ apply_parameter_mappings()

void StateMachine::apply_parameter_mappings	(	const std::string &	state_name,
		const State::SharedPtr &	state )

private

Applies this container's parameter mappings to a direct child.

Parameters

state_name	The child state name.
state	The child state instance.

◆ 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 currently active child state.

This lightweight cancel request is forwarded to the active child state. If the state machine continues executing afterwards, its running status is restored inside the execution loop so later cancel requests can still be propagated.

Reimplemented from yasmin::State.

◆ cancel_state_machine()

void StateMachine::cancel_state_machine ( )

Cancels the complete state machine execution.

This requests a hard stop of the current state machine. The request is propagated recursively to an active child state machine and causes the execution loop to abort by throwing StateMachineCancelException.

◆ compose_remappings()

Remappings StateMachine::compose_remappings	(	const Remappings &	parent_remappings,
		const Remappings &	state_remappings )

staticprivate

Compose parent and state blackboard remappings.

The state remappings are resolved against the currently active parent remappings. If a state target already points to a remapped parent key, the resulting mapping is flattened to the final parent target.

Parameters

parent_remappings	Remappings currently active in the parent scope.
state_remappings	Remappings defined by the current state.

Returns: Combined remapping table with state entries resolved through the parent scope.

◆ configure()

void StateMachine::configure ( )

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.

◆ 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's specific logic.

Parameters

blackboard A shared pointer to the Blackboard to use during execution.

Returns: A string representing the outcome of the execution.

This method is intended to be overridden by derived classes to provide specific execution logic.

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

const ParameterMappingsMap & StateMachine::get_parameter_mappings ( ) const

noexcept

Gets all parameter mappings.

Returns: A constant reference to the parameter mappings.

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

void StateMachine::set_parameter_mappings	(	const std::string &	state_name,
		const ParameterMappings &	parameter_mappings )

Sets parameter mappings for a child state.

Each mapping entry is interpreted as: child_parameter -> parent_parameter

Parameters

state_name	The child state name.
parameter_mappings	The parameter mappings to apply.

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

◆ throw_if_cancel_state_machine_requested()

void StateMachine::throw_if_cancel_state_machine_requested ( )

private

Throws if a hard state machine cancel was requested.

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

◆ wait_for_current_state()

std::string StateMachine::wait_for_current_state ( )

private

Waits until a current state is available while execution is active.

Returns: The current state name, or an empty string if execution is no longer active.

Member Data Documentation

◆ cancel_state_machine_requested

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

private

Flag to indicate that a hard state machine cancel was requested.

◆ configured

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

private

Flag to indicate if the state machine has been configured.

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

◆ execution_active

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

private

Flag to indicate whether the execute loop is currently active.

◆ name

std::string yasmin::StateMachine::name

private

◆ parameter_mappings

ParameterMappingsMap yasmin::StateMachine::parameter_mappings

private

Per-child parameter mappings applied during configure().

◆ 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

Public Types

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Member Typedef Documentation

◆ EndCallbackType

◆ StartCallbackType

◆ TransitionCallbackType

Constructor & Destructor Documentation

◆ StateMachine() [1/2]

◆ StateMachine() [2/2]

◆ ~StateMachine()

Member Function Documentation

◆ add_end_cb()

◆ add_start_cb()

◆ add_state()

◆ add_transition_cb()

◆ apply_parameter_mappings()

◆ call_end_cbs()

◆ call_start_cbs()

◆ call_transition_cbs()

◆ cancel_state()

◆ cancel_state_machine()

◆ compose_remappings()

◆ configure()

◆ execute() [1/2]

◆ execute() [2/2]

◆ get_current_state()

◆ get_name()

◆ get_parameter_mappings()

◆ get_start_state()

◆ get_states()

◆ get_transitions()

◆ operator()() [1/2]

◆ operator()() [2/2]

◆ set_current_state()

◆ set_name()

◆ set_parameter_mappings()

◆ set_sigint_handler()

◆ set_start_state()

◆ throw_if_cancel_state_machine_requested()

◆ to_string()

◆ validate()

◆ wait_for_current_state()

Member Data Documentation

◆ cancel_state_machine_requested

◆ configured

◆ current_state

◆ current_state_cond

◆ current_state_mutex

◆ end_cbs

◆ execution_active

◆ name

◆ parameter_mappings

◆ remappings

◆ start_cbs

◆ start_state

◆ states

◆ transition_cbs

◆ transitions

◆ validated