Represents a state in a state machine. More...

#include <state.hpp>

Inheritance diagram for yasmin::State:

[legend]

Collaboration diagram for yasmin::State:

[legend]

Public Member Functions
	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.
virtual std::string	execute (Blackboard::SharedPtr blackboard)
	Executes the state's specific logic.
virtual void	configure ()
	Configures the state before execution.
virtual void	cancel_state ()
	Cancels the current state execution.
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.
virtual std::string	to_string () const
	Converts the state to a string representation.

Protected Attributes
Outcomes	outcomes
	The possible outcomes of this state.

Private Member Functions
StateMetadata &	get_metadata_ref () const
	Gets a mutable reference to this state's metadata.
void	set_status (StateStatus new_status)
	Sets the current status of the state.
StateStatus	get_status () const
	Gets the current status of the state.

Private Attributes
std::atomic< StateStatus >	status {StateStatus::IDLE}
	Current status of the state.

Detailed Description

Represents a state in a state machine.

The State class defines a state that can execute actions and manage outcomes. It maintains information about its execution status and the possible outcomes of its execution.

Constructor & Destructor Documentation

◆ State()

State::State ( const Outcomes & outcomes )

Shared pointer type for State.

Constructs a State with a set of possible outcomes.

Parameters

outcomes A set of possible outcomes for this state.

◆ ~State()

State::~State ( )

virtual

Virtual destructor.

Cleans up externally-stored metadata for this instance.

Member Function Documentation

◆ add_input_key() [1/4]

void State::add_input_key ( const BlackboardKeyInfo & key_info )

Adds an input key to the state's metadata.

Parameters

key_info Information about the input key.

◆ add_input_key() [2/4]

void State::add_input_key ( const std::string & key_name )

Adds an input key with a name only.

Parameters

key_name The name of the input key.

◆ add_input_key() [3/4]

void State::add_input_key	(	const std::string &	key_name,
		const std::string &	description )

Adds an input key with a name and description.

Parameters

key_name	The name of the input key.
description	Human-readable description of the input key.

◆ add_input_key() [4/4]

template<typename T>

void yasmin::State::add_input_key	(	const std::string &	key_name,
		const std::string &	description,
		T	default_value )

inline

Adds an input key with a name, default value and description.

Template Parameters

T	The type of the default value.

Parameters

key_name	The name of the input key.
description	Human-readable description of the input key.
default_value	The default value for the key.

◆ add_output_key() [1/3]

void State::add_output_key ( const BlackboardKeyInfo & key_info )

Adds an output key to the state's metadata.

Parameters

key_info Information about the output key.

◆ add_output_key() [2/3]

void State::add_output_key ( const std::string & key_name )

Adds an output key with a name only.

Parameters

key_name The name of the output key.

◆ add_output_key() [3/3]

void State::add_output_key	(	const std::string &	key_name,
		const std::string &	description )

Adds an output key with a name and description.

Parameters

key_name	The name of the output key.
description	Human-readable description of the output key.

◆ cancel_state()

virtual void yasmin::State::cancel_state ( )

inlinevirtual

Cancels the current state execution.

This method sets the status to CANCELED and logs the action.

Reimplemented in yasmin::Concurrence, yasmin::PyState, yasmin::StateMachine, yasmin_ros::ActionState< ActionT >, yasmin_ros::ActionState< Fibonacci >, yasmin_ros::MonitorState< MsgT >, and yasmin_ros::MonitorState< nav_msgs::msg::Odometry >.

◆ configure()

virtual void yasmin::State::configure ( )

inlinevirtual

Configures the state before execution.

This method can be overridden by derived classes to allocate resources, validate configuration, or initialize internal state. The default implementation does nothing.

Reimplemented in ConfigurableConcurrentState, ConfigurableLeafState, yasmin::Concurrence, yasmin::PyState, yasmin::StateMachine, yasmin_ros::RosDeserializeCppState, yasmin_ros::RosSerializeCppState, and yasmin_ros::TfBufferState.

◆ copy_parameter_from()

void State::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.

Parameters

source_state	The source state.
source_parameter_name	The parameter name in the source state.
target_parameter_name	The parameter name in this state.

◆ declare_parameter() [1/4]

void State::declare_parameter ( const BlackboardKeyInfo & parameter_info )

Declares a parameter in the state metadata.

Parameters

parameter_info Information about the parameter.

◆ declare_parameter() [2/4]

void State::declare_parameter ( const std::string & parameter_name )

Declares a parameter with a name only.

Parameters

parameter_name The name of the parameter.

◆ declare_parameter() [3/4]

void State::declare_parameter	(	const std::string &	parameter_name,
		const std::string &	description )

Declares a parameter with a name and description.

Parameters

parameter_name	The name of the parameter.
description	Human-readable description of the parameter.

◆ declare_parameter() [4/4]

template<typename T>

void yasmin::State::declare_parameter	(	const std::string &	parameter_name,
		const std::string &	description,
		T	default_value )

inline

Declares a parameter with a name, description, and default value.

Template Parameters

T	The type of the default value.

Parameters

parameter_name	The name of the parameter.
description	Human-readable description of the parameter.
default_value	The default value for the parameter.

◆ execute()

virtual std::string yasmin::State::execute ( Blackboard::SharedPtr blackboard )

inlinevirtual

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 in BarState, BarState, BarState, BarState, BarState, BarState, BarState, BlockingWriteState, ConfigurableConcurrentState, ConfigurableLeafState, DelayedStartStateMachine, FooState, FooState, FooState, FooState, FooState, FooState, FooState, StateWithAllTypes, StateWithDefaults, yasmin::CbState, yasmin::Concurrence, yasmin::PyState, yasmin::StateMachine, yasmin_ros::ActionState< ActionT >, yasmin_ros::ActionState< Fibonacci >, yasmin_ros::GetParametersState, yasmin_ros::MonitorState< MsgT >, yasmin_ros::MonitorState< nav_msgs::msg::Odometry >, yasmin_ros::PublisherState< MsgT >, yasmin_ros::PublisherState< std_msgs::msg::Int32 >, yasmin_ros::RosDeserializeCppState, yasmin_ros::RosSerializeCppState, yasmin_ros::ServiceState< ServiceT >, yasmin_ros::ServiceState< example_interfaces::srv::AddTwoInts >, and yasmin_ros::TfBufferState.

◆ get_description()

const std::string & State::get_description ( ) const

Gets the description of this state.

Returns: The description of the state.

◆ get_input_keys()

const std::vector< BlackboardKeyInfo > & State::get_input_keys ( ) const

Gets the input keys metadata.

Returns: A constant reference to the vector of input key information.

◆ get_metadata()

const StateMetadata & State::get_metadata ( ) const

Gets the complete state metadata.

Returns: A constant reference to the state metadata.

◆ get_metadata_ref()

StateMetadata & State::get_metadata_ref ( ) const

private

Gets a mutable reference to this state's metadata.

Metadata is stored externally (not as a direct member) to preserve ABI compatibility with plugins compiled against earlier versions of the State class.

◆ get_outcome_description()

const std::string & State::get_outcome_description ( const std::string & outcome ) const

Gets the human-readable description for an outcome.

Parameters

outcome The outcome name.

Returns: The description of the outcome, or an empty string if none exists.

Exceptions

std::invalid_argument If the outcome is not part of this state.

◆ get_outcome_descriptions()

const std::unordered_map< std::string, std::string > & State::get_outcome_descriptions ( ) const

Gets all outcome descriptions.

Returns: A constant reference to the outcome description map.

◆ get_outcomes()

Outcomes const & State::get_outcomes ( ) const

noexcept

Gets the set of possible outcomes for this state.

Returns: A constant reference to the set of possible outcomes.

◆ get_output_keys()

const std::vector< BlackboardKeyInfo > & State::get_output_keys ( ) const

Gets the output keys metadata.

Returns: A constant reference to the vector of output key information.

◆ get_parameter()

template<typename T>

T yasmin::State::get_parameter ( const std::string & parameter_name ) const

inline

Gets a parameter from the state-local parameter storage.

Template Parameters

T	The parameter type.

Parameters

parameter_name The parameter name.

Returns: The stored parameter value.

◆ get_parameters()

const std::vector< BlackboardKeyInfo > & State::get_parameters ( ) const

Gets the declared parameter metadata.

Returns: A constant reference to the vector of parameter metadata.

◆ get_parameters_blackboard()

Blackboard::SharedPtr State::get_parameters_blackboard ( ) const

Gets the private parameter blackboard of this state.

This is primarily exposed for internal framework use and Python bindings.

Returns: Shared pointer to the private parameter blackboard.

◆ get_status()

StateStatus State::get_status ( ) const

private

Gets the current status of the state.

Returns: The current StateStatus.

◆ has_parameter()

bool State::has_parameter ( const std::string & parameter_name ) const

Checks if a parameter exists in the state-local parameter storage.

Parameters

parameter_name The parameter name.

Returns: True if the parameter exists, otherwise false.

◆ is_canceled()

bool State::is_canceled ( ) const

noexcept

Checks if the state has been canceled.

Returns: True if the state is canceled, otherwise false.

◆ is_completed()

bool State::is_completed ( ) const

noexcept

Checks if the state has completed execution.

Returns: True if the state is completed, otherwise false.

◆ is_idle()

bool State::is_idle ( ) const

noexcept

Checks if the state is idle.

Returns: True if the state is idle, otherwise false.

◆ is_parameter_declared()

bool State::is_parameter_declared ( const std::string & parameter_name ) const

Checks whether a parameter was declared in the state metadata.

Parameters

parameter_name The parameter name.

Returns: True if the parameter was declared, otherwise false.

◆ is_running()

bool State::is_running ( ) const

noexcept

Checks if the state is currently running.

Returns: True if the state is running, otherwise false.

◆ operator()()

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

void State::set_description ( const std::string & description )

Sets the description for this state.

Parameters

description The description of the state.

◆ set_outcome_description()

void State::set_outcome_description	(	const std::string &	outcome,
		const std::string &	description )

Sets a human-readable description for an outcome.

Parameters

outcome	The outcome name.
description	The description of the outcome.

Exceptions

std::invalid_argument If the outcome is not part of this state.

◆ set_parameter()

template<typename T>

void yasmin::State::set_parameter	(	const std::string &	parameter_name,
		T	value )

inline

Sets a parameter in the state-local parameter storage.

Template Parameters

T	The parameter type.

Parameters

parameter_name	The parameter name.
value	The parameter value.

◆ set_status()

void State::set_status ( StateStatus new_status )

private

Sets the current status of the state.

Parameters

new_status The new status to set.

◆ to_string()

std::string State::to_string ( ) const

virtual

Converts the state to a string representation.

Returns: A string representation of the state.

This method retrieves the demangled name of the class for a readable string representation.

Reimplemented in yasmin::Concurrence, yasmin::PyState, and yasmin::StateMachine.

Member Data Documentation

◆ outcomes

Outcomes yasmin::State::outcomes

protected

The possible outcomes of this state.

◆ status

std::atomic<StateStatus> yasmin::State::status {StateStatus::IDLE}

private

Current status of the state.

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

yasmin/include/yasmin/state.hpp
yasmin/src/yasmin/state.cpp

Public Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ State()

◆ ~State()

Member Function Documentation

◆ add_input_key() [1/4]

◆ add_input_key() [2/4]

◆ add_input_key() [3/4]

◆ add_input_key() [4/4]

◆ add_output_key() [1/3]

◆ add_output_key() [2/3]

◆ add_output_key() [3/3]

◆ cancel_state()

◆ configure()

◆ copy_parameter_from()

◆ declare_parameter() [1/4]

◆ declare_parameter() [2/4]

◆ declare_parameter() [3/4]

◆ declare_parameter() [4/4]

◆ execute()

◆ get_description()

◆ get_input_keys()

◆ get_metadata()

◆ get_metadata_ref()

◆ get_outcome_description()

◆ get_outcome_descriptions()

◆ get_outcomes()

◆ get_output_keys()

◆ get_parameter()

◆ get_parameters()

◆ get_parameters_blackboard()

◆ get_status()

◆ has_parameter()

◆ is_canceled()

◆ is_completed()

◆ is_idle()

◆ is_parameter_declared()

◆ is_running()

◆ operator()()

◆ set_description()

◆ set_outcome_description()

◆ set_parameter()

◆ set_status()

◆ to_string()

Member Data Documentation

◆ outcomes

◆ status