Class State

• Defined in File state.hpp

Inheritance Relationships

Derived Types

• public yasmin::CbState (Class CbState)

• public yasmin::Concurrence (Class Concurrence)

• public yasmin::StateMachine (Class StateMachine)

Class Documentation

class State

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.

Subclassed by yasmin::CbState, yasmin::Concurrence, yasmin::StateMachine

Public Functions

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.

virtual ~State()

Virtual destructor.

Cleans up externally-stored metadata for this instance.

Blackboard::SharedPtr 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.

bool is_idle() const noexcept

Checks if the state is idle.

Returns:

True if the state is idle, otherwise false.

bool is_running() const noexcept

Checks if the state is currently running.

Returns:

True if the state is running, otherwise false.

bool is_canceled() const noexcept

Checks if the state has been canceled.

Returns:

True if the state is canceled, otherwise false.

bool is_completed() const noexcept

Checks if the state has completed execution.

Returns:

True if the state is completed, otherwise false.

std::string operator()(Blackboard::SharedPtr blackboard)

Executes the state and returns the outcome.

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.

Parameters:

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

Throws:

std::logic_error – If the outcome is not in the set of outcomes.

Returns:

A string representing the outcome of the execution.

inline virtual std::string execute(Blackboard::SharedPtr blackboard)

Executes the state’s specific logic.

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

Parameters:

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

Returns:

A string representing the outcome of the execution.

inline virtual void configure()

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.

inline virtual void cancel_state()

Cancels the current state execution.

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

Outcomes const &get_outcomes() const noexcept

Gets the set of possible outcomes for this state.

Returns:

A constant reference to the set of possible outcomes.

void set_description(const std::string &description)

Sets the description for this state.

Parameters:

description – The description of the state.

const std::string &get_description() const

Gets the description of this state.

Returns:

The description of the state.

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

Throws:

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

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

Gets the human-readable description for an outcome.

Parameters:

outcome – The outcome name.

Throws:

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

Returns:

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

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

Gets all outcome descriptions.

Returns:

A constant reference to the outcome description map.

void add_input_key(const BlackboardKeyInfo &key_info)

Adds an input key to the state’s metadata.

Parameters:

key_info – Information about the input key.

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

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

template<typename T>
inline 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.

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.

void add_output_key(const BlackboardKeyInfo &key_info)

Adds an output key to the state’s metadata.

Parameters:

key_info – Information about the output key.

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

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

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

Gets the input keys metadata.

Returns:

A constant reference to the vector of input key information.

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

Gets the output keys metadata.

Returns:

A constant reference to the vector of output key information.

void declare_parameter(const BlackboardKeyInfo &parameter_info)

Declares a parameter in the state metadata.

Parameters:

parameter_info – Information about the parameter.

void declare_parameter(const std::string &parameter_name)

Declares a parameter with a name only.

Parameters:

parameter_name – The name of the parameter.

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

template<typename T>
inline 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.

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.

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

template<typename T>
inline T get_parameter(const std::string &parameter_name) const

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.

template<typename T>
inline void set_parameter(const std::string &parameter_name, T value)

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.

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

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.

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.

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

Gets the declared parameter metadata.

Returns:

A constant reference to the vector of parameter metadata.

const StateMetadata &get_metadata() const

Gets the complete state metadata.

Returns:

A constant reference to the state metadata.

virtual std::string to_string() const

Converts the state to a string representation.

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

Returns:

A string representation of the state.

Protected Attributes

Outcomes outcomes

The possible outcomes of this state.