QP::QHsm Class Reference

Hierarchical State Machine class (QHsm-style state machine implementation strategy). More...

#include <qp.hpp>

Inheritance diagram for QP::QHsm:

Public Member Functions
void	init (void const *const e, std::uint_fast8_t const qsId) override
	Virtual override to take the top-most initial transition in QHsm.
void	dispatch (QEvt const *const e, std::uint_fast8_t const qsId) override
	Virtual override to dispatch an event to QHsm.
bool	isIn (QStateHandler const stateHndl) noexcept override
	Check whether the HSM is in a given state.
QStateHandler	getStateHandler () const noexcept override
	Virtual method for getting the current state handler.
QStateHandler	childState (QStateHandler const parentHndl) noexcept
	Obtain the current active child state of a given parent in QP::QMsm.
virtual void	init (std::uint_fast8_t const qsId)
	Virtual function to take the top-most initial transition in the state machine (overloaded).
Public Member Functions inherited from QP::QAsm
virtual	~QAsm ()=default
	Virtual destructor of the QP::QAsm abstract base class.
QStateHandler	state () const noexcept
QMState const *	stateObj () const noexcept

Protected Member Functions
	QHsm (QStateHandler const initial) noexcept
Protected Member Functions inherited from QP::QAsm
	QAsm () noexcept
	Constructor of the QP::QAsm base class.
QState	tran (QStateHandler const target) noexcept
	Internal helper function to take a state transition in sublclasses of QP::QAsm.
QState	tran_hist (QStateHandler const hist) noexcept
	Internal helper function to take a state transition to history in sublclasses of QP::QAsm.
QState	super (QStateHandler const superstate) noexcept
	Internal helper function to indicate superstate of a given state in sublclasses of QP::QAsm.
QState	qm_tran (void const *const tatbl) noexcept
	Internal helper function to take a state transition in QP::QMsm.
QState	qm_tran_init (void const *const tatbl) noexcept
QState	qm_tran_hist (QMState const *const hist, void const *const tatbl) noexcept
	Internal helper function to take a state transition to history in QP::QMsm.
QState	qm_entry (QMState const *const s) noexcept
	Internal helper function to execute state entry actions in QP::QMsm.
QState	qm_exit (QMState const *const s) noexcept
	Internal helper function to execute state exit actions in QP::QMsm.

Private Member Functions
std::size_t	tran_simple_ (std::array< QStateHandler, MAX_NEST_DEPTH_ > &path, std::uint_fast8_t const qsId)
	Implementation of a simple state transition segment.
std::size_t	tran_complex_ (std::array< QStateHandler, MAX_NEST_DEPTH_ > &path, std::uint_fast8_t const qsId)
	Implementation of a complex state transition segment.
void	enter_target_ (std::array< QStateHandler, MAX_NEST_DEPTH_ > &path, std::size_t const depth, std::uint_fast8_t const qsId)
	Implementation of entry to the target state configuration.
std::size_t	tran_simple_ (std::array< QStateHandler, MAX_NEST_DEPTH_ > &path, std::uint_fast8_t const qsId)
std::size_t	tran_complex_ (std::array< QStateHandler, MAX_NEST_DEPTH_ > &path, std::uint_fast8_t const qsId)
void	enter_target_ (std::array< QStateHandler, MAX_NEST_DEPTH_ > &path, std::size_t const depth, std::uint_fast8_t const qsId)

Static Private Attributes
static constexpr std::size_t	MAX_NEST_DEPTH_ {6U}

Friends
class	QS

Additional Inherited Members
Static Public Member Functions inherited from QP::QAsm
static constexpr QState	Q_HANDLED ()
static constexpr QState	Q_UNHANDLED ()
static constexpr QState	QM_HANDLED ()
static constexpr QState	QM_UNHANDLED ()
static constexpr QState	QM_SUPER ()
static QState	top (void *const me, QEvt const *const e) noexcept
	Top state handler that ignores all events.
Public Attributes inherited from QP::QAsm
QAsmAttr	m_state
	Current state (pointer to the current state-handler function).
QAsmAttr	m_temp
	Temporary storage for target/act-table etc.
Static Public Attributes inherited from QP::QAsm
static constexpr QState	Q_RET_SUPER {0U}
static constexpr QState	Q_RET_UNHANDLED {1U}
static constexpr QState	Q_RET_HANDLED {2U}
static constexpr QState	Q_RET_TRAN {3U}
static constexpr QState	Q_RET_TRAN_HIST {4U}
static constexpr QState	Q_RET_IGNORED {5U}
static constexpr QState	Q_RET_ENTRY {6U}
static constexpr QState	Q_RET_EXIT {7U}
static constexpr QState	Q_RET_TRAN_INIT {8U}
static constexpr QSignal	Q_EMPTY_SIG {0U}
static constexpr QSignal	Q_ENTRY_SIG {1U}
static constexpr QSignal	Q_EXIT_SIG {2U}
static constexpr QSignal	Q_INIT_SIG {3U}
static constexpr QMState const *	QM_STATE_NULL { nullptr }
static constexpr QActionHandler const	Q_ACTION_NULL { nullptr }

Detailed Description

Hierarchical State Machine class (QHsm-style state machine implementation strategy).

Details
QP::QHsm represents a Hierarchical State Machine (HSM) with full support for hierarchical nesting of states, entry/exit actions, initial transitions, and transitions to history in any composite state. This class is designed for ease of manual coding of HSMs in C++, but it is also supported by the QM modeling tool.

Note

QP::QHsm is not intended to be instantiated directly, but rather serves as the abstract base class for derivation of state machines in the QP/C++ Application.

Backward Traceability

• REQ_QP_SM_00: QP/C++ Framework component shall provide support for hierarchical state machines for Active Objects and for passive stateful objects in the QP/C++ Application.
• REQ_QP_SM_10: QP/C++ Framework component shall support multiple and interchangeable State Machine Implementation Strategies
• DES_QP_QHsm: Design view: QP::QHsm State machine class.

Usage
The following example illustrates how to derive a state machine class from QHsm. Please note that the QHsm member super is defined as the FIRST member of the derived class.

// Calculator class with a state machine...
class Calc : public QP::QHsm { // <== inherit QP::QHsm
public:
    static Calc inst;
 
private:
    double m_op1;
    double m_op2;
    uint8_t m_oper1;
    uint8_t m_oper2;
 
public:
    // ctor
    Calc() : : QHsm(Q_STATE_CAST(&Calc::initial)) {...}
 
protected:
    Q_STATE_DECL(initial);
    Q_STATE_DECL(on);
    Q_STATE_DECL(ready);
    Q_STATE_DECL(begin);
    . . .
}; // class Calc

Definition at line 301 of file qp.hpp.

Constructor & Destructor Documentation

QHsm()

QP::QHsm::QHsm ( QStateHandler const initial )

explicitprotectednoexcept

Definition at line 142 of file qep_hsm.cpp.

Member Function Documentation

init() [1/2]

void QP::QHsm::init ( void const *const e, std::uint_fast8_t const qsId )

overridevirtual

Virtual override to take the top-most initial transition in QHsm.

Details
Synchronously executes the top-most initial transition in QHsm-type state machine.

Parameters

[in]	e	pointer to the initialization parameter
[in]	qsId	QS-id of this state machine (for QS local filter)

Implements QP::QAsm.

Definition at line 150 of file qep_hsm.cpp.

dispatch()

void QP::QHsm::dispatch ( QEvt const *const e, std::uint_fast8_t const qsId )

overridevirtual

Virtual override to dispatch an event to QHsm.

Details
Synchronously dispatches an event for processing to a QHsm-type state machine.

Parameters

[in]	e	pointer to the event to be dispatched to the MSM
[in]	qsId	QS-id of this state machine (for QS local filter)

Backward Traceability

• DES_QP_QHsm_dispatch: Design view: QHsm event dispatching

Forward Traceability

• DVR_QP_PCLP_732: loss of sign in accessing array element path[ip])

Implements QP::QAsm.

Definition at line 225 of file qep_hsm.cpp.

isIn()

bool QP::QHsm::isIn ( QP::QStateHandler const state )

overridevirtualnoexcept

Check whether the HSM is in a given state.

Details
Check if a given state is part of the current active state configuration in ::QHsm subclasses. Please note that in a hierarchical state machine, to "be in a state" means also to be in a superstate of of the state.

See also

QP::QAsm::isIn()

Attention

This function must be called only on a state machine that is in the "stable state configuration". Among others, this means that the state machine cannot call it in the middle of its own transition.

Backward Traceability

• REQ_QP_SM_25: All State Machine Implementation Strategies provided by the QP/C++ Framework component might supply a method for checking if a state machine is in a given state.

Implements QP::QAsm.

Definition at line 549 of file qep_hsm.cpp.

getStateHandler()

QStateHandler QP::QHsm::getStateHandler ( ) const

overridevirtualnoexcept

Virtual method for getting the current state handler.

Details
This virtual call applies to all subclasses of QP::QAsm, such as: QP::QHsm, QP::QMsm, QP::QActive, and QP::QMActive.

Returns

the current state-handler of the type QP::QStateHandler (pointer to function)

Note

This function can be called in any context (including from a critical section) and also not necessarily in the "stable state configuration". When called during a state transition in the state machine, it returns the source state.

Backward Traceability

• REQ_QP_SM_26: All State Machine Implementation Strategies provided by the QP/C++ Framework component might supply a method for obtaining the current state.

Usage
The following example illustrates how to obtain the current state handler of an Active Object:

QStateHandler handler = myAO->getStateHandler();

Implements QP::QAsm.

Definition at line 610 of file qep_hsm.cpp.

childState()

QStateHandler QP::QHsm::childState ( QP::QStateHandler const parent )

noexcept

Obtain the current active child state of a given parent in QP::QMsm.

Details
Finds the child state of the given parent, such that this child state is an ancestor of the currently active state. The main purpose of this function is to support **shallow history*transitions in state machines derived from QMsm.

Parameters

[in]

parent

pointer to the state-handler

Returns

the child of a given parent state-handler, which is an ancestor of the currently active state. For the corner case when the currently active state is the given parent state, function returns the parent state.

Note

This function is used in QM for auto-generating code for state history (shallow history)

Definition at line 579 of file qep_hsm.cpp.

tran_simple_() [1/2]

std::size_t QP::QHsm::tran_simple_ ( std::array< QStateHandler, MAX_NEST_DEPTH_ > & path, std::uint_fast8_t const qsId )

private

Implementation of a simple state transition segment.

Details
Determines the type of a simple transition (A-D, see Figure SDS-SM-STRAN). If the simple transition type is found, the function exits the source states to the LCA, otherwise the function returns 2.

Parameters

[in,out]	path	array containing the target state-handler in path[0], and source state-handler in path[2]. Upon return, path[] contains the sequence of state handlers to be entered in QHsm::enter_target_()
[in]	qsId	QS-id of this state machine (for QS local filter)

Returns

the number of state nesting levels of the path[] array to be entered in QHsm::QHsm_enter_target_(). Return value > 1 indicates higher complexity transition and the need to call QHsm_tran_complex_().

Note

This function is for internal use only and should be called exclusively from QP::QHsm::dispatch().

Backward Traceability

• DES_QP_QHsm_dispatch: Design view: QHsm event dispatching

Forward Traceability

tran_complex_() [1/2]

std::size_t QP::QHsm::tran_complex_ ( std::array< QStateHandler, MAX_NEST_DEPTH_ > & path, std::uint_fast8_t const qsId )

private

Implementation of a complex state transition segment.

Details
Determines the type of a complex transition (E-H, see Figure SDS-SM-CTRAN). Next, the function exits the source states to the LCA.

Parameters

[in,out]	path	array containing the target state-handler in path[0], and source state-handler in path[2]. Upon return, path[] contains the sequence of state handlers to be entered in QHsm::QHsm_enter_target_()
[in]	qsId	QS-id of this state machine (for QS local filter)

Returns

the number of state nesting levels of the path[] array to be entered in QHsm::enter_target_().

Note

This function is for internal use only and should be called exclusively from QHsm::dispatch().

Backward Traceability

• DES_QP_QHsm_dispatch: Design view: QHsm event dispatching

Forward Traceability

enter_target_() [1/2]

void QP::QHsm::enter_target_ ( std::array< QStateHandler, MAX_NEST_DEPTH_ > & path, std::size_t const depth, std::uint_fast8_t const qsId )

private

Implementation of entry to the target state configuration.

Details
This function performs entry to the target state configuration by following the nested initial transition. This process can be recursive, which the function implements by iteration.

Parameters

[in,out]	path[]	contains the sequence of state handlers to be entered. It is also reused for entry-path for initial transition.
[in]	depth	the initial number of nesting levels in the path[] array.
[in]	qsId	QS-id of this state machine (for QS local filter)

Note

This function is for internal use only and should be called exclusively from QHsm::init() and QHsm::dispatch().

Backward Traceability

• DES_QP_QHsm_dispatch: Design view: QHsm event dispatching

Forward Traceability

tran_simple_() [2/2]

std::size_t tran_simple_ ( std::array< QStateHandler, MAX_NEST_DEPTH_ > & path, std::uint_fast8_t const qsId )

private

Definition at line 328 of file qep_hsm.cpp.

tran_complex_() [2/2]

std::size_t tran_complex_ ( std::array< QStateHandler, MAX_NEST_DEPTH_ > & path, std::uint_fast8_t const qsId )

private

Definition at line 395 of file qep_hsm.cpp.

enter_target_() [2/2]

void enter_target_ ( std::array< QStateHandler, MAX_NEST_DEPTH_ > & path, std::size_t const depth, std::uint_fast8_t const qsId )

private

Definition at line 484 of file qep_hsm.cpp.

init() [2/2]

void QP::QAsm::init ( std::uint_fast8_t const qsId )

virtual

Virtual function to take the top-most initial transition in the state machine (overloaded).

Details
Synchronously executes the top-most initial transition in a state machine. This overloaded version takes no initialization parameter.

Parameters

[in]

qsId

QS-id of this state machine (for QS local filter)

Reimplemented from QP::QAsm.

Definition at line 218 of file qf_act.cpp.

Friends And Related Symbol Documentation

QS

friend class QS

friend

Definition at line 337 of file qp.hpp.

Member Data Documentation

MAX_NEST_DEPTH_

std::size_t QP::QHsm::MAX_NEST_DEPTH_ {6U}

staticconstexprprivate

Definition at line 321 of file qp.hpp.

---

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

• qp.hpp
• qep_hsm.cpp
• qp.dox