Class StateModel

Class Documentation

class StateModel

The state model that can be used to enforce valid state transitions.

This class should be used in a has-a relationship rather than classes extending from it.

This class stores the current state and allows only valid transitions based on events.

This class is thread safe and calls the handle_event method uses a threading primitive to ensure that state transition is allowed and is atomic.

Public Functions

inline explicit StateModel(const std::string &_entity)

Construct a new State Model object.

Parameters

_entity – the name of the entity that the state model corresponds to. This is used in logging to provide as context of what entity generating the log message.

virtual ~StateModel() = default

Destroy the StateModel object.

inline State get_state() const

Return the current state of the state model.

Returns

State current state of the state model

inline std::string get_state_name() const

Get the name of the current state.

Returns

std::string

inline std::string get_state_name(State _state) const

Get the name of the state.

Parameters

_state – the state to get the name of

Returns

std::string

void handle_event(StateModelEvent event)

Handle event that should cause a state transition.

If the event is not valid for the current state, then an exception will be thrown.

Parameters

event – the event that should cause a state transition to occur.

Throws

ska::pst::common::pst_state_transition_error – if there is no transition allows for the current state and event.

bool is_transition_allowed(StateModelEvent event) const

Check if the current event is allowed to occur given the current state.

Returns

true if the event is either a RuntimeError or that the given State and StateModelEvent are a valid combination is allowed.

inline bool is_state(State _state) const

Check if the current state is the same as what was provided.

Parameters

_state – the state to check against.

Returns

true if the current state is the same as one provided.

Returns

false if the current state is not the same as the one provided.

bool wait_for_state(State required_state)

Wait for the state to change to required state or RuntimeError.

Parameters

required_state – the expected state to wait for

Returns

true if the change of state is the required_state

Returns

false if the change of state is to RuntimeError and required state is not RuntimeError

bool wait_for_not_state(State required, unsigned milliseconds)

Wait for the state model to achieve any state other than the required state, within the timeout.

Parameters

  • required – the required state for the state model to change from

  • milliseconds – timeout in milliseconds

Returns

true if the state model did achieve any state other than the required state within the timeout.

Returns

false if the state model did not achieve any state other than the required state within the timeout

inline const std::map<std::string, std::string> get_log_context() const

Return mapped diagnostic context key/value pairs, that the constructor initialises to: { “entity”: entity}.

Returns

const std::map<std::string, std::string> list of key/value pairs

Public Static Functions

static inline std::string get_name(StateModelEvent event)

Return the name of the specified event.

Parameters

event – the event to get the name of.

Returns

std::string name of the event

static inline std::string get_name(State state)

Return the name of the specified state.

Parameters

state – state whose name to return

Returns

std::string name of the state

Protected Functions

inline void set_state(State _state)

Set the state object.

this is provided to allow for testing. It should not be used for production code as classes should not extend this class.

Parameters

_state – the state to set the state machine to.