QP::QMsm Class Reference

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

#include <qp.hpp>

Inheritance diagram for QP::QMsm:

Public Member Functions
void	init (void const *const e, std::uint_fast8_t const qsId) override
	Implementation of the top-most initial transition in QP::QMsm.
void	dispatch (QEvt const *const e, std::uint_fast8_t const qsId) override
	Implementation of dispatching events to a QP::QMsm.
bool	isIn (QStateHandler const stateHndl) noexcept override
	Tests if a given state is part of the current active state configuration.
QStateHandler	getStateHandler () const noexcept override
	Obtain the current active state from a MSM (read only).
QMState const *	childStateObj (QMState const *const parentHndl) const 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

Static Public Member Functions
static QMState const *	topQMState () noexcept
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.

Protected Member Functions
	QMsm (QStateHandler const initial) noexcept
	Constructor of QP::QMsm.
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
QState	execTatbl_ (QMTranActTable const *const tatbl, std::uint_fast8_t const qsId)
	Execute a transition-action table in QP::QMsm.
void	exitToTranSource_ (QMState const *const curr_state, QMState const *const tran_source, std::uint_fast8_t const qsId)
	Exit the given current-state up to the given tran-source in QP::QMsm.
QState	enterHistory_ (QMState const *const hist, std::uint_fast8_t const qsId)
	Enter the history of a given state in QP::QMsm.

Friends
class	QS

Additional Inherited Members
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 (QMsm-style state machine implementation strategy).

Details
QP::QMsm (QM State Machine) provides a more efficient state machine implementation strategy than QP::QHsm, but requires the use of the QM modeling tool, but are the fastest and need the least run-time support (the smallest event-processor taking up the least code space).

Note

QP::QMsm is not intended to be instantiated directly, but rather serves as the abstract base class for derivation of state machines in the application code.

Backward Traceability

• SRS_QP_SM_21: QP/C++ Framework component should provide a State Machine Implementation Strategy optimized for "automatic code generation"
• SDS_QP_QMsm: QMsm State machine class.

Usage
The following example illustrates how to derive a state machine class from QP::QMsm.

class ToasterOven : public QP::QMsm { // <== inherits QP::QMsm
public:
    ToasterOven();
 
public:
    // ctor
    ToasterOven() : QMsm(Q_STATE_CAST(&ToasterOven::initial)) {...}
 
protected:
    QM_STATE_DECL( initial);
    QM_STATE_DECL( doorClosed);
    QM_ACTION_DECL(doorClosed_e);
    QM_ACTION_DECL(doorClosed_x);
    QM_ACTION_DECL(doorClosed_i);
    . . .
}; // class ToastOven

Definition at line 341 of file qp.hpp.

Constructor & Destructor Documentation

QMsm()

QP::QMsm::QMsm ( QStateHandler const initial )

explicitprotectednoexcept

Constructor of QP::QMsm.

Details
Performs the first step of QMsm initialization by assigning the initial pseudostate to the currently active state of the state machine.

Parameters

[in]

initial

the top-most initial transition for the MSM.

Usage
The following example illustrates how to invoke QMsm() constructor in the "constructor" of a derived state machine:

void Calc::Calc()
  : QMsm(Q_STATE_CAST(&Calc::initial)); // <===
    . . .
{
    . . .
}

Forward Traceability

Member Function Documentation

init() [1/2]

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

overridevirtual

Implementation of the top-most initial transition in QP::QMsm.

Details
This function synchronously executes the top-most initial transition in a state machine.

Parameters

[in]	e	pointer to an extra parameter (might be NULL)
[in]	qsId	QS-id of this state machine (for QS local filter)

Implements QP::QAsm.

dispatch()

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

overridevirtual

Implementation of dispatching events to a QP::QMsm.

Details
This function synchronously dispatches an event for processing to a state machine. The processing of an event represents one run-to-completion (RTC) step.

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

• SDS_QP_QMsm_dispatch: QMsm Event Dispatching

Forward Traceability

Implements QP::QAsm.

isIn()

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

overridevirtualnoexcept

Tests if a given state is part of the current active state configuration.

Details
Check if a given state is part of the current active state configuration in ::QMsm 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

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

getStateHandler()

QStateHandler QP::QMsm::getStateHandler ( ) const

overridevirtualnoexcept

Obtain the current active state from a MSM (read only).

Returns

the current active state-handler

Note

This function is used for state history (deep history) in the auto-generated code by the QM modeling tool. Reimplemented from QP::QAsm.

Implements QP::QAsm.

childStateObj()

QMState const * QP::QMsm::childStateObj ( QMState const *const parentHndl ) const

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]

parentHndl

pointer to the state-handler object

Returns

the child state (pointer to QP::QMState state object) of a given parentHndl state, which is an ancestor of the currently active state. For the corner case when the currently active state is the given parentHndl state-handler, function returns the parentHndl state.

Note

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

topQMState()

QMState const * QP::QMsm::topQMState ( )

staticnoexcept

execTatbl_()

QState QP::QMsm::execTatbl_ ( QMTranActTable const *const tatbl, std::uint_fast8_t const qsId )

private

Execute a transition-action table in QP::QMsm.

Execute transition-action table.

Details
This helper function executes the provided transition-action table calling each action in the table until nullptr (the end of the table) is reached.

Parameters

[in]	tatbl	transition-action table to execute
[in]	qsId	QS-id of this state machine (for QS local filter)

Returns

The status of the last invoked action in the table. If this status is ::Q_RET_TRAN_INIT, the function is called again to enter the transition-action table associated with that nested initial transition

Note

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

Backward Traceability

• SDS_QP_QMsm_dispatch: QMsm Event Dispatching

Forward Traceability

Details
Helper function to execute transition sequence in a transition-action table.

Parameters

[in]	tatbl	pointer to the transition-action table
[in]	qsId	QS-id of this state machine (for QS local filter)

Returns

status of the last action from the transition-action table.

Note

This function is for internal use inside the QEP event processor and should **not* be called directly from the applications.

exitToTranSource_()

void QP::QMsm::exitToTranSource_ ( QMState const *const curr_state, QMState const *const tran_source, std::uint_fast8_t const qsId )

private

Exit the given current-state up to the given tran-source in QP::QMsm.

Exit the current state up to the explicit transition source.

Details
This helper function scans the state hierarchy (by following the state.superstate links) and calls the exit action for each state object, starting with the current-state and ending at the tran-source state.

Parameters

[in]	curr_state	pointer to the current state object
[in]	tran_source	pointer to the transition source object
[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 QMsm::dispatch().

Backward Traceability

• SDS_QP_QMsm_dispatch: QMsm Event Dispatching

Forward Traceability

Details
Static helper function to exit the current state configuration to the transition source, which in a hierarchical state machine might be a superstate of the current state.

Parameters

[in]	curr_state	pointer to the current state
[in]	tran_source	pointer to the transition source state
[in]	qsId	QS-id of this state machine (for QS local filter)

Forward Traceability

enterHistory_()

QState QP::QMsm::enterHistory_ ( QMState const *const hist, std::uint_fast8_t const qsId )

private

Enter the history of a given state in QP::QMsm.

Enter history of a composite state.

Details
This helper function dynamically enters the given history state, which is the substate of m_state.obj.

Parameters

[in]	hist	pointer to the history state to be entered
[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 QMsm::dispatch().

Backward Traceability

• SDS_QP_QMsm_dispatch: QMsm Event Dispatching

Forward Traceability

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

  Details
  Static helper function to execute the segment of transition to history after entering the composite state and

  Parameters

  [in]	hist	pointer to the history substate
  [in]	qsId	QS-id of this state machine (for QS local filter)

  Returns

  Q_RET_TRAN_INIT, if an initial transition has been executed in the last entered state or 0 (Q_RET_SUPER) if no such transition was taken.

  Forward Traceability
  

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 373 of file qp.hpp.

---

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

• qp.hpp
• qp.dox