QP::QActiveDummy Class Reference

Dummy Active Object class for testing (inherits QP::QActive) More...

#include "qs.hpp"

Inheritance diagram for QP::QActiveDummy:

Public Member Functions
	QActiveDummy ()
	ctor
void	start (QPrioSpec const prioSpec, QEvt const **const qSto, std::uint_fast16_t const qLen, void *const stkSto, std::uint_fast16_t const stkSize, void const *const par) override
	Starts execution of an active object and registers the object with the framework.
void	start (QPrioSpec const prioSpec, QEvt const **const qSto, std::uint_fast16_t const qLen, void *const stkSto, std::uint_fast16_t const stkSize) override
	Overloaded start function (no initialization parameter)
void	init (void const *const e, std::uint_fast8_t const qs_id) override
	Executes the top-most initial transition in QP::QHsm.
void	init (std::uint_fast8_t const qs_id) override
	overloaded init(qs_id)
void	dispatch (QEvt const *const e, std::uint_fast8_t const qs_id) override
	Dispatches an event to QP::QHsm.
bool	post_ (QEvt const *const e, std::uint_fast16_t const margin, void const *const sender) noexcept override
	Posts an event e directly to the event queue of the active object using the First-In-First-Out (FIFO) policy.
void	postLIFO (QEvt const *const e) noexcept override
	Posts an event e directly to the event queue of the active object using the Last-In-First-Out (LIFO) policy.
Public Member Functions inherited from QP::QActive
virtual void	start (QPrioSpec const prioSpec, QEvt const **const qSto, std::uint_fast16_t const qLen, void *const stkSto, std::uint_fast16_t const stkSize, void const *const par)
	Starts execution of an active object and registers the object with the framework.
virtual void	start (QPrioSpec const prioSpec, QEvt const **const qSto, std::uint_fast16_t const qLen, void *const stkSto, std::uint_fast16_t const stkSize)
	Overloaded start function (no initialization parameter)
void	stop ()
	Stops execution of an active object and removes it from the framework's supervision.
virtual bool	post_ (QEvt const *const e, std::uint_fast16_t const margin, void const *const sender) noexcept
	Posts an event e directly to the event queue of the active object using the First-In-First-Out (FIFO) policy.
virtual void	postLIFO (QEvt const *const e) noexcept
	Posts an event e directly to the event queue of the active object using the Last-In-First-Out (LIFO) policy.
QEvt const *	get_ () noexcept
	Get an event from the event queue of an active object.
void	subscribe (enum_t const sig) const noexcept
	Subscribes for delivery of signal sig to the active object.
void	unsubscribe (enum_t const sig) const noexcept
	Unsubscribes from the delivery of signal sig to the active object.
void	unsubscribeAll () const noexcept
	Unsubscribes from the delivery of all signals to the active object.
bool	defer (QEQueue *const eq, QEvt const *const e) const noexcept
	Defer an event to a given separate event queue.
bool	recall (QEQueue *const eq) noexcept
	Recall a deferred event from a given event queue.
std::uint_fast16_t	flushDeferred (QEQueue *const eq) const noexcept
	Flush the specified deferred queue 'eq'.
std::uint_fast8_t	getPrio () const noexcept
	Get the priority of the active object.
void	setAttr (std::uint32_t attr1, void const *attr2=nullptr)
	Generic setting of additional attributes (useful in QP ports)
QF_OS_OBJECT_TYPE &	getOsObject () noexcept
	accessor to the OS-object for extern "C" functions, such as the QK or QXK schedulers
QF_THREAD_TYPE &	getThread () noexcept
	accessor to the Thread for extern "C" functions, such as the QK or QXK schedulers
void	register_ () noexcept
	Register this active object to be managed by the framework.
void	unregister_ () noexcept
	Un-register the active object from the framework.
Public Member Functions inherited from QP::QHsm
virtual void	init (void const *const e, std::uint_fast8_t const qs_id)
	Executes the top-most initial transition in QP::QHsm.
virtual void	init (std::uint_fast8_t const qs_id)
	overloaded init(qs_id)
virtual void	dispatch (QEvt const *const e, std::uint_fast8_t const qs_id)
	Dispatches an event to QP::QHsm.
QStateHandler	state () const noexcept
	Obtain the current state (state handler function)
virtual QStateHandler	getStateHandler () noexcept
	Get the current state handler of the QP::QHsm.
bool	isIn (QStateHandler const s) noexcept
	Tests if a given state is part of the current active state configuration.
QStateHandler	childState (QStateHandler const parent) noexcept
	Obtain the current active child state of a given parent.

Additional Inherited Members
Public Types inherited from QP::QHsm
enum	ReservedSig : QSignal { Q_EMPTY_SIG , Q_ENTRY_SIG , Q_EXIT_SIG , Q_INIT_SIG }
	Reserved signals by the HSM-style state machine implementation strategy. More...
enum	QStateRet : std::uint_fast8_t {   Q_RET_SUPER , Q_RET_SUPER_SUB , Q_RET_UNHANDLED , Q_RET_HANDLED ,   Q_RET_IGNORED , Q_RET_ENTRY , Q_RET_EXIT , Q_RET_NULL ,   Q_RET_TRAN , Q_RET_TRAN_INIT , Q_RET_TRAN_EP , Q_RET_TRAN_HIST ,   Q_RET_TRAN_XP }
	All possible return values from state-handlers. More...
Static Public Member Functions inherited from QP::QActive
static void	psInit (QSubscrList *const subscrSto, enum_t const maxSignal) noexcept
	Publish-subscribe initialization.
static void	publish_ (QEvt const *const e, void const *const sender, std::uint_fast8_t const qs_id) noexcept
	Publish event to all subscribers of a given signal e->sig
static void	thread_ (QActive *act)
	Thread routine for executing an active object act
Static Public Member Functions inherited from QP::QHsm
static QState	top (void *const me, QEvt const *const e) noexcept
	The top-state handler.
Public Attributes inherited from QP::QActive
QF_EQUEUE_TYPE	m_eQueue
	OS-dependent event-queue type.
QF_OS_OBJECT_TYPE	m_osObject
	OS-dependent per-thread object.
QF_THREAD_TYPE	m_thread
	OS-dependent representation of the thread of the active object.
std::uint8_t	m_prio
	QF-priority [1..QF_MAX_ACTIVE] of this AO.
std::uint8_t	m_pthre
	preemption-threshold [1..QF_MAX_ACTIVE] of this AO.
Static Public Attributes inherited from QP::QActive
static QActive *	registry_ [QF_MAX_ACTIVE+1U]
	Internal array of registered active objects.
static QSubscrList *	subscrList_
	pointer to the array of all subscriber AOs for a given event signal
static enum_t	maxPubSignal_
	The maximum published signal (the size of the subscrList_ array)
Static Public Attributes inherited from QP::QHsm
static constexpr std::int_fast8_t	MAX_NEST_DEPTH_ {6}
	Maximum nesting depth of states in HSM.
Protected Member Functions inherited from QP::QActive
	QActive (QStateHandler const initial) noexcept
	protected constructor (abstract class)
void	setPrio (QPrioSpec const prio) noexcept
	Set the priority of the active object.
Protected Member Functions inherited from QP::QHsm
	QHsm (QStateHandler const initial) noexcept
	protected constructor of QHsm
QState	tran (QStateHandler const target) noexcept
	Helper function to specify a state transition.
QState	tran_hist (QStateHandler const hist) noexcept
	Helper function to specify a transition to history.
QState	super (QStateHandler const superstate) noexcept
	Helper function to specify the superstate of a given state.
QState	qm_tran (void const *const tatbl) noexcept
	Helper function to specify a regular state transition in a QM state-handler.
QState	qm_tran_init (void const *const tatbl) noexcept
	Helper function to specify an initial state transition in a QM state-handler.
QState	qm_tran_hist (QMState const *const hist, void const *const tatbl) noexcept
	Helper function to specifiy a transition to history in a QM state-handler.
QState	qm_tran_ep (void const *const tatbl) noexcept
	Helper function to specify a transition to an entry point to a submachine state in a QM state-handler.
QState	qm_tran_xp (QActionHandler const xp, void const *const tatbl) noexcept
	Helper function to specify a transition to an exit point from a submachine state in a QM state-handler.
QState	qm_entry (QMState const *const s) noexcept
	Helper function to specify a state entry in a QM state-handler.
QState	qm_exit (QMState const *const s) noexcept
	Helper function to specify a state exit in a QM state-handler.
QState	qm_sm_exit (QMState const *const s) noexcept
	Helper function to specify a submachine exit in a QM state-handler.
QState	qm_super_sub (QMState const *const s) noexcept
	Helper function to call in a QM state-handler when it passes the event to the host submachine state to handle an event.

Detailed Description

QActiveDummy is a test double for the role of collaborating active objects in QUTest unit testing.

Definition at line 1550 of file qs.hpp.

Constructor & Destructor Documentation

QActiveDummy()

QP::QActiveDummy::QActiveDummy

(

)

Definition at line 429 of file qutest.cpp.

Member Function Documentation

start() [1/2]

void QP::QActiveDummy::start ( QPrioSpec const  prioSpec, QEvt const **const  qSto, std::uint_fast16_t const  qLen, void *const  stkSto, std::uint_fast16_t const  stkSize, void const *const  par  )

overridevirtual

Starts execution of the AO and registers the AO with the framework.

Parameters

[in]	prioSpec	priority specification of the AO containing the QF-priority and (optionally) preemption-threshold of this AO (for preemptive kernels that support it). See also QP::QPrioSpec.
[in]	qSto	pointer to the storage for the ring buffer of the event queue
[in]	qLen	length of the event queue [# QP::QEvt* pointers]
[in]	stkSto	pointer to the stack storage (might be nullptr)
[in]	stkSize	stack size [bytes]
[in]	par	pointer to an extra parameter (might be nullptr)

Usage

The following example shows starting an AO when a per-task stack is needed:

 
main() {
    . . .
    static Philo l_philo[N];  // N Philosopher active objects
    static QEvt const *l_philQueueSto[N][N]; // storage for Philo event queues
    static int l_philoStk[N][256]; // stacks for the Philosopher active objects
    for (std::uint8_t n = 0U; n < N; ++n) {
        uint32_t options = 0x1234U;
        ie.philNum = n;
        l_philo[n].start(
            n*10U + 1U,                 // QP priority [1..QF_MAX_ACTIVE]
            l_philoQueueSto[n],         // queue storage
            Q_DIM(l_philoQueueSto[n]),  // queue depth [QEvt* pointers]
            l_philoStk[n],              // RTOS stack storage
            sizeof(l_philoStk[n]),      // RTOS stack size [bytes]
            &options);                  // initialization parameter
    }
    . . .
}

Precondition

AO cannot be started from an ISR, and the stack storage must not be provided, because the QK kernel does not need per-AO stacks.

stack storage must not be provided because the QV kernel does not need per-AO stacks.

AO cannot be started:

• from an ISR;
• the stack storage must NOT be provided
• preemption-threshold is NOT provided (because QXK kernel does not support preemption-threshold scheduling)

Reimplemented from QP::QActive.

Definition at line 434 of file qutest.cpp.

start() [2/2]

void QP::QActiveDummy::start ( QPrioSpec const  prioSpec, QEvt const **const  qSto, std::uint_fast16_t const  qLen, void *const  stkSto, std::uint_fast16_t const  stkSize  )

inlineoverridevirtual

Reimplemented from QP::QActive.

Definition at line 1562 of file qs.hpp.

init() [1/2]

void QP::QActiveDummy::init ( void const *const  e, std::uint_fast8_t const  qs_id  )

overridevirtual

Executes the top-most initial transition in a HSM.

Parameters

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

Note

Must be called exactly once before the QP::QHsm::dispatch().

RQP103 RQP120I RQP120D

Precondition

ctor must have been executed and initial tran NOT taken

Reimplemented from QP::QHsm.

Definition at line 457 of file qutest.cpp.

init() [2/2]

void QP::QActiveDummy::init ( std::uint_fast8_t const  qs_id )

overridevirtual

Executes the top-most initial transition in a HSM (overloaded).

Parameters

[in]

qs_id

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

Attention

QHsm::init() must be called exactly once before QHsm::dispatch()

Reimplemented from QP::QHsm.

Definition at line 480 of file qutest.cpp.

dispatch()

void QP::QActiveDummy::dispatch ( QEvt const *const  e, std::uint_fast8_t const  qs_id  )

overridevirtual

Dispatches an event for processing to a hierarchical state machine. The event dispatching represents one run-to-completion (RTC) step.

Parameters

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

Attention

This state machine must be initialized by calling QP::QHsm::init() exactly once before calling QP::QHsm::dispatch().

RQP103 RQP120A RQP120B RQP120C RQP120D RQP120E

Precondition

the current state must be initialized and the state configuration must be stable

RQP120A

RQP120E

RQP120C

RQP120B

RQP120I

Reimplemented from QP::QHsm.

Definition at line 485 of file qutest.cpp.

post_()

bool QP::QActiveDummy::post_ ( QEvt const *const  e, std::uint_fast16_t const  margin, void const *const  sender  )

overridevirtualnoexcept

Direct event posting is the simplest asynchronous communication method available in QF.

Parameters

[in]	e	pointer to the event to be posted
[in]	margin	number of required free slots in the queue after posting the event or QF::NO_MARGIN.
[in]	sender	pointer to a sender object (used in QS only)

Returns

'true' (success) if the posting succeeded (with the provided margin) and 'false' (failure) when the posting fails.

Attention

For margin == QF::NO_MARGIN, this function will assert internally if the event posting fails. In that case, it is unnecessary to check the retrun value from this function.

Note

This function might be implemented differentyl in various QP/C++ ports. The provided implementation assumes that the QP::QEQueue class is used for the QP::QActive event queue.

Usage

extern QActive * const AO_Table;
 
Q_STATE_DEF(Philo, hungry) {
    QP::QState status_;
    switch (e->sig) {
        case Q_ENTRY_SIG: {
            TableEvt *pe = Q_NEW(TableEvt, HUNGRY_SIG);
            pe->philoNum = PHILO_ID(this);
            AO_Table->POST(pe, this); // <----
            status_ = Q_RET_HANDLED;
            break;
        }
        . . .
        default: {
            status_ = super(&top);
            break;
        }
    }
    return status_;
}

See also

QActive::postLIFO()

Precondition

event pointer must be valid

Reimplemented from QP::QActive.

Definition at line 501 of file qutest.cpp.

postLIFO()

void QP::QActiveDummy::postLIFO ( QEvt const *const  e )

overridevirtualnoexcept

The LIFO policy should be used only for self-posting and with caution, because it alters order of events in the queue.

Parameters

[in]

e

pointer to the event to be posted

Attention

This function asserts internally if the posting fails.

Note

This function might be implemented differentyl in various QP/C++ ports. The provided implementation assumes that the QP::QEQueue class is used for the QActive event queue.

See also

QActive::post()

Reimplemented from QP::QActive.

Definition at line 560 of file qutest.cpp.

---

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

• qs.hpp
• qutest.cpp