Class StateMachine

• Defined in File state_machine.hpp

Inheritance Relationships

Base Type

• public yasmin::State (Class State)

Class Documentation

class StateMachine : public yasmin::State

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.

Public Functions

StateMachine(std::set<std::string> outcomes)

Construct a new StateMachine object.

Parameters:

outcomes – A set of possible outcomes for the state machine.

void add_state(std::string name, std::shared_ptr<State> state, std::map<std::string, std::string> transitions)

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.

Throws:

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

void add_state(std::string name, std::shared_ptr<State> state)

Adds a state to the state machine without transitions.

Parameters:

• name – The name of the state.

• state – A shared pointer to the State object representing the new state.

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

Throws:

std::invalid_argument – If the state name is empty or not registered.

std::string get_start_state()

Retrieves the name of the start state.

Returns:

The name of the start state.

std::map<std::string, std::shared_ptr<State>> const &get_states()

Gets a constant reference to the map of states.

Returns:

A constant reference to the map of states.

std::map<std::string, std::map<std::string, std::string>> const &get_transitions()

Gets a constant reference to the map of transitions.

Returns:

A constant reference to the map of transitions.

std::string get_current_state()

Retrieves the current state name.

Returns:

The name of the current state.

void add_start_cb(StartCallbackType cb, std::vector<std::string> args = {})

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

Parameters:

• cb – The callback function to execute.

• args – Optional arguments to pass to the callback.

void add_transition_cb(TransitionCallbackType cb, std::vector<std::string> args = {})

Adds a callback function for state transitions.

Parameters:

• cb – The callback function to execute.

• args – Optional arguments to pass to the callback.

void add_end_cb(EndCallbackType cb, std::vector<std::string> args = {})

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

Parameters:

• cb – The callback function to execute.

• args – Optional arguments to pass to the callback.

void call_start_cbs(std::shared_ptr<yasmin::blackboard::Blackboard> blackboard, const std::string &start_state)

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.

void call_transition_cbs(std::shared_ptr<yasmin::blackboard::Blackboard> blackboard, const std::string &from_state, const std::string &to_state, const std::string &outcome)

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.

void call_end_cbs(std::shared_ptr<yasmin::blackboard::Blackboard> blackboard, const std::string &outcome)

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.

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

Throws:

std::runtime_error – If the state machine is misconfigured.

virtual std::string execute(std::shared_ptr<blackboard::Blackboard> blackboard) override

Executes the state machine.

Parameters:

blackboard – A shared pointer to the blackboard used during execution.

Throws:

std::runtime_error – If the execution cannot be completed due to invalid states or transitions.

Returns:

The outcome of the state machine execution.

std::string execute()

Executes the state machine using a default blackboard.

Returns:

The outcome of the state machine execution.

std::string operator()()

Invokes the state machine using a default blackboard.

Returns:

The outcome of the state machine execution.

virtual void cancel_state() override

Cancels the current state execution.

virtual std::string to_string()

Converts the state machine to a string representation.

Returns:

A string describing the state machine and its states.