QActive active object (based on QP::QHsm implementation) More...

#include <qf.hpp>

Inheritance diagram for QActive:

Collaboration diagram for QActive:

Public Member Functions
virtual void	start (std::uint_fast8_t const prio, 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. More...

virtual void	start (std::uint_fast8_t const prio, QEvt const *const qSto, std::uint_fast16_t const qLen, void const stkSto, std::uint_fast16_t const stkSize)
	Overloaded start function (no initialization event) More...

void	stop (void)
	Stops execution of an active object and removes it from the framework's supervision. More...

virtual bool	post_ (QEvt const const e, std::uint_fast16_t const margin, void const const sender) noexcept

virtual void	postLIFO (QEvt const *const e) noexcept
	Posts an event directly to the event queue of the active object using the Last-In-First-Out (LIFO) policy. More...

void	unsubscribeAll (void) const noexcept
	Un-subscribes from the delivery of all signals to the active object. More...

void	subscribe (enum_t const sig) const noexcept
	Subscribes for delivery of signal `sig` to the active object. More...

void	unsubscribe (enum_t const sig) const noexcept
	Un-subscribes from the delivery of signal `sig` to the active object. More...

bool	defer (QEQueue const eq, QEvt const const e) const noexcept
	Defer an event to a given separate event queue. More...

bool	recall (QEQueue *const eq) noexcept
	Recall a deferred event from a given event queue. More...

std::uint_fast16_t	flushDeferred (QEQueue *const eq) const noexcept
	Flush the specified deferred queue 'eq'. More...

std::uint_fast8_t	getPrio (void) const noexcept
	Get the priority of the active object. More...

void	setPrio (std::uint_fast8_t const prio)
	Set the priority of the active object. More...

void	setAttr (std::uint32_t attr1, void const *attr2=nullptr)
	Generic setting of additional attributes (useful in QP ports) More...

QEvt const *	get_ (void) noexcept
	Get an event from the event queue of an active object. More...

Public Member Functions inherited from QHsm
virtual	~QHsm ()
	virtual destructor More...

virtual void	init (void const *const e, std::uint_fast8_t const qs_id)
	executes the top-most initial transition in QP::QHsm More...

virtual void	init (std::uint_fast8_t const qs_id)
	overloaded init(qs_id) More...

virtual void	dispatch (QEvt const *const e, std::uint_fast8_t const qs_id)
	Dispatches an event to QHsm. More...

bool	isIn (QStateHandler const s) noexcept
	Tests if a given state is part of the current active state configuration. More...

QStateHandler	state (void) const noexcept
	Obtain the current state (state handler function) More...

QStateHandler	childState (QStateHandler const parent) noexcept
	Obtain the current active child state of a given parent. More...

Data Fields
std::uint8_t	m_prio
	QF priority (1..QF_MAX_ACTIVE) of this active object. More...

Protected Member Functions
	QActive (QStateHandler const initial) noexcept
	protected constructor (abstract class) More...

Protected Member Functions inherited from QHsm
	QHsm (QStateHandler const initial) noexcept
	Protected constructor of QHsm. More...

QState	tran (QStateHandler const target) noexcept
	Helper function to specify a state transition. More...

QState	tran_hist (QStateHandler const hist) noexcept
	Helper function to specify a transition to history. More...

QState	super (QStateHandler const superstate) noexcept
	Helper function to specify the superstate of a given state. More...

QState	qm_tran (void const *const tatbl) noexcept
	Helper function to specify a regular state transition in a QM state-handler. More...

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

QState	qm_tran_init (void const *const tatbl) noexcept
	Helper function to specify an initial state transition in a QM state-handler. More...

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

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

QState	qm_entry (QMState const *const s) noexcept
	Helper function to specify a state entry in a QM state-handler. More...

QState	qm_exit (QMState const *const s) noexcept
	Helper function to specify a state exit in a QM state-handler. More...

virtual QStateHandler	getStateHandler () noexcept
	Get the current state handler of the HSM. More...

QState	qm_sm_exit (QMState const *const s) noexcept
	Helper function to specify a submachine exit in a QM state-handler. More...

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

Friends
class	QF

class	QTimeEvt

class	QTicker

class	QActiveDummy

Additional Inherited Members
Static Public Member Functions inherited from QHsm
static QState	top (void const me, QEvt const const e) noexcept
	the top-state. More...

Static Public Attributes inherited from QHsm
static constexpr QState	Q_RET_SUPER {static_cast<QState>(0)}
	event passed to the superstate to handle More...

static constexpr QState	Q_RET_SUPER_SUB {static_cast<QState>(1)}
	event passed to submachine superstate More...

static constexpr QState	Q_RET_UNHANDLED {static_cast<QState>(2)}
	event unhandled due to a guard evaluating to 'false' More...

static constexpr QState	Q_RET_HANDLED {static_cast<QState>(3)}
	event handled (internal transition) More...

static constexpr QState	Q_RET_IGNORED {static_cast<QState>(4)}
	event silently ignored (bubbled up to top) More...

static constexpr QState	Q_RET_ENTRY {static_cast<QState>(5)}
	state entry action executed More...

static constexpr QState	Q_RET_EXIT {static_cast<QState>(6)}
	state exit action executed More...

static constexpr QState	Q_RET_NULL {static_cast<QState>(7)}
	return value without any effect More...

static constexpr QState	Q_RET_TRAN {static_cast<QState>(8)}
	regular transition taken More...

static constexpr QState	Q_RET_TRAN_INIT {static_cast<QState>(9)}
	initial transition taken More...

static constexpr QState	Q_RET_TRAN_EP {static_cast<QState>(10)}
	entry-point transition into a submachine More...

static constexpr QState	Q_RET_TRAN_HIST {static_cast<QState>(11)}
	transition to history of a given state More...

static constexpr QState	Q_RET_TRAN_XP {static_cast<QState>(12)}
	exit-point transition out of a submachine More...

Protected Types inherited from QHsm
enum	ReservedHsmSignals : QSignal { Q_ENTRY_SIG = 1 , Q_EXIT_SIG , Q_INIT_SIG }

Detailed Description

QActive active object (based on QP::QHsm implementation)

Description: Active objects in QP are encapsulated tasks (each embedding a state machine and an event queue) that communicate with one another asynchronously by sending and receiving events. Within an active object, events are processed in a run-to-completion (RTC) fashion, while QF encapsulates all the details of thread-safe event exchange and queuing.

QP::QActive represents an active object that uses the QP::QHsm-style implementation strategy for state machines. This strategy is tailored to manual coding, but it is also supported by the QM modeling tool. The resulting code is slower than in the QP::QMsm-style implementation strategy.

Note: QP::QActive is not intended to be instantiated directly, but rather serves as the base class for derivation of active objects in the applications.

See also: QP::QMActive

Usage: The following example illustrates how to derive an active object from QP::QActive.
class Philo : public QActive { // derives from QActive

private:

uint8_t m_num; // number of this philosopher

QTimeEvt m_timeEvt; // to timeout thining or eating

public:

Philo::Philo() // constructor

: QActive(&initial), // superclass' constructor

m_timeEvt(TIMEOUT_SIG, this, 0U)

{}

protected:

Q_STATE_DECL(initial);

Q_STATE_DECL(thinking);

Q_STATE_DECL(hungry);

Q_STATE_DECL(eating);

};

uint8_t
unsigned char uint8_t
exact-width 8-bit unsigned int
Definition: 16bit/stdint.h:29

QP::QActive::QTimeEvt
friend class QTimeEvt
Definition: qf.hpp:293

QP::QHsm::QActive
friend class QActive
Definition: qep.hpp:470

Q_STATE_DECL
#define Q_STATE_DECL(state_)
Macro to generate a declaration of a state-handler, state-caller and a state-object for a given state...
Definition: qep.hpp:619

Definition at line 144 of file qf.hpp.

Constructor & Destructor Documentation

◆ QActive()

QActive ( QStateHandler const initial )

protectednoexcept

protected constructor (abstract class)

Definition at line 44 of file qf_qact.cpp.

Member Function Documentation

◆ start() [1/2]

void start	(	std::uint_fast8_t const	prio,
		QEvt const **const	qSto,
		std::uint_fast16_t const	qLen,
		void *const	stkSto,
		std::uint_fast16_t const	stkSize,
		void const *const	par
	)

virtual

Starts execution of an active object and registers the object with the framework.

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

Parameters

[in]	prio	priority at which to start the active object
[in]	qSto	pointer to the storage for the ring buffer of the event queue (used only with the built-in QP::QEQueue)
[in]	qLen	length of the event queue (in events)
[in]	stkSto	pointer to the stack storage (must be nullptr in QV)
[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
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

main() {

. . .

for (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

}

. . .

}

uint32_t
unsigned long int uint32_t
exact-width 32-bit unsigned int
Definition: 16bit/stdint.h:31

Q_DIM
#define Q_DIM(array_)
Helper macro to calculate static dimension of a 1-dim array_.
Definition: qassert.h:337

Precondition

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

the priority must be in range and the stack storage must not be provided, because the QV kernel does not need per-AO stacks.

AO cannot be started:

from an ISR;
the priority must be in range;
the stack storage must NOT be provided (because the QXK kernel does not need per-AO stacks).

Reimplemented in QXThread, and QActiveDummy.

Definition at line 173 of file qk.cpp.

◆ start() [2/2]

virtual void start	(	std::uint_fast8_t const	prio,
		QEvt const **const	qSto,
		std::uint_fast16_t const	qLen,
		void *const	stkSto,
		std::uint_fast16_t const	stkSize
	)

inlinevirtual

Overloaded start function (no initialization event)

Reimplemented in QXThread, and QActiveDummy.

Definition at line 200 of file qf.hpp.

◆ stop()

void stop ( void )

Stops execution of an active object and removes it from the framework's supervision.

Attention: QActive::stop() must be called only from the AO that is about to stop its execution. By that time, any pointers or references to the AO are considered invalid (dangling) and it becomes illegal for the rest of the application to post events to the AO.

Definition at line 112 of file qutest.cpp.

◆ post_()

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

virtualnoexcept

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

Parameters

[in,out]	e	pointer to the event to be posted
[in]	margin	number of required free slots in the queue after posting the event. The special value QP::QF_NO_MARGIN means that this function will assert if posting fails.
[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: Should be called only via the macro POST() or POST_X().

Note: The QP::QF_NO_MARGIN value of the margin argument is special and denotes situation when the post() operation is assumed to succeed (event delivery guarantee). An assertion fires, when the event cannot be delivered in this case.

Usage: extern QActive *AO_Table;

QP::QState Philo::hungry(Philo * const me, QP::QEvt const * const e) {

QP::QState status;

switch (e->sig) {

case Q_ENTRY_SIG: {

TableEvt *pe = Q_NEW(TableEvt, HUNGRY_SIG);

pe->philoNum = PHILO_ID(me);

AO_Table->POST(pe, me);

status = Q_HANDLED();

break;

}

. . .

default: {

status = Q_SUPER(&QHsm::top);

break;

}

}

return status;

}

QP::QHsm::Q_ENTRY_SIG
@ Q_ENTRY_SIG
signal for entry actions
Definition: qep.hpp:372

QP::QHsm::top
static QState top(void *const me, QEvt const *const e) noexcept
the top-state.
Definition: qep_hsm.cpp:224

QP::QState
std::uint_fast8_t QState
Type returned from state-handler functions.
Definition: qep.hpp:223

Q_HANDLED
#define Q_HANDLED()
Macro to specify that the event was handled.
Definition: qep.hpp:631

Q_NEW
#define Q_NEW(evtT_, sig_)
Allocate a dynamic event.
Definition: qf.hpp:715

Q_SUPER
#define Q_SUPER(state_)
Definition: qpcpp.hpp:152

QP::QEvt
QEvt base class.
Definition: qep.hpp:209

QP::QEvt::sig
QSignal sig
signal of the event instance
Definition: qep.hpp:210

See also: QActive::postLIFO()

Precondition: event pointer must be valid

Reimplemented in QXThread, QActiveDummy, and QTicker.

Definition at line 90 of file qf_actq.cpp.

◆ postLIFO()

void postLIFO ( QEvt const *const e )

virtualnoexcept

Posts an event directly to the event queue of the active object using the Last-In-First-Out (LIFO) policy.

Description: posts an event to the event queue of the active object using the Last-In-First-Out (LIFO) policy.

Note: 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 post to the queue

See also: QActive::post_()

Reimplemented in QXThread, QActiveDummy, and QTicker.

Definition at line 228 of file qf_actq.cpp.

◆ unsubscribeAll()

void unsubscribeAll ( void ) const

noexcept

Un-subscribes from the delivery of all signals to the active object.

Description: This function is part of the Publish-Subscribe event delivery mechanism available in QF. Un-subscribing from all events means that the framework will stop posting any published events to the event queue of the active object.

Note: Due to the latency of event queues, an active object should NOT assume that no events will ever be dispatched to the state machine of the active object after un-subscribing from all events. The events might be already in the queue, or just about to be posted and the un-subscribe operation will not flush such events. Also, the alternative event-delivery mechanisms, such as direct event posting or time events, can be still delivered to the event queue of the active object.

See also: QP::QF::publish_(), QP::QActive::subscribe(), and QP::QActive::unsubscribe()

Definition at line 293 of file qf_ps.cpp.

◆ subscribe()

void subscribe ( enum_t const sig ) const

noexcept

Subscribes for delivery of signal sig to the active object.

Description: This function is part of the Publish-Subscribe event delivery mechanism available in QF. Subscribing to an event means that the framework will start posting all published events with a given signal sig to the event queue of the active object.

Parameters

[in] sig event signal to subscribe

The following example shows how the Table active object subscribes to three signals in the initial transition:

Q_State_DEF(Table, initial) {
    uint8_t n;
    subscribe(HUNGRY_SIG);    // subscribe to HUNGRY
    subscribe(DONE_SIG);      // subscribe to DONE
    subscribe(TERMINATE_SIG); // subscribe to TERMINATE
    for (n = 0; n < N; ++n) {
        m_fork_[n] = FREE;
        m_isHungry_[n] = 0;
    }
    return tran(&serving);
}

See also: QP::QF::publish_(), QP::QActive::unsubscribe(), and QP::QActive::unsubscribeAll()

Definition at line 204 of file qf_ps.cpp.

◆ unsubscribe()

void unsubscribe ( enum_t const sig ) const

noexcept

Un-subscribes from the delivery of signal sig to the active object.

Description: This function is part of the Publish-Subscribe event delivery mechanism available in QF. Un-subscribing from an event means that the framework will stop posting published events with a given signal sig to the event queue of the active object.

Parameters

[in] sig event signal to unsubscribe

Note: Due to the latency of event queues, an active object should NOT assume that a given signal sig will never be dispatched to the state machine of the active object after un-subscribing from that signal. The event might be already in the queue, or just about to be posted and the un-subscribe operation will not flush such events.; Un-subscribing from a signal that has never been subscribed in the first place is considered an error and QF will raise an assertion.

See also: QP::QF::publish_(), QP::QActive::subscribe(), and QP::QActive::unsubscribeAll()

Precondition: the singal and the prioriy must be in ragne, the AO must also

Definition at line 248 of file qf_ps.cpp.

◆ defer()

bool defer	(	QEQueue *const	eq,
		QEvt const *const	e
	)		const

noexcept

Defer an event to a given separate event queue.

Description: This function is part of the event deferral support. An active object uses this function to defer an event e to the QF-supported native event queue eq. QF correctly accounts for another outstanding reference to the event and will not recycle the event at the end of the RTC step. Later, the active object might recall one event at a time from the event queue.

Parameters

[in]	eq	pointer to a "raw" thread-safe queue to recall an event from.
[in]	e	pointer to the event to be deferred

Returns: 'true' (success) when the event could be deferred and 'false' (failure) if event deferral failed due to overflowing the queue.

An active object can use multiple event queues to defer events of different kinds.

See also: QP::QActive::recall(), QP::QEQueue, QP::QActive::flushDeferred()

Definition at line 77 of file qf_defer.cpp.

◆ recall()

bool recall ( QEQueue *const eq )

noexcept

Recall a deferred event from a given event queue.

Description: This function is part of the event deferral support. An active object uses this function to recall a deferred event from a given QF event queue. Recalling an event means that it is removed from the deferred event queue eq and posted (LIFO) to the event queue of the active object.

Parameters

[in] eq pointer to a "raw" thread-safe queue to recall an event from.

Returns: 'true' if an event has been recalled and 'false' if not.

Note: An active object can use multiple event queues to defer events of different kinds.

See also: QP::QActive::recall(), QP::QEQueue, QP::QActive::postLIFO_()

Definition at line 113 of file qf_defer.cpp.

◆ flushDeferred()

std::uint_fast16_t flushDeferred ( QEQueue *const eq ) const

noexcept

Flush the specified deferred queue 'eq'.

Description: This function is part of the event deferral support. An active object can use this function to flush a given QF event queue. The function makes sure that the events are not leaked.

Parameters

[in] eq pointer to a "raw" thread-safe queue to flush.

Returns: the number of events actually flushed from the queue.

See also: QP::QActive::defer(), QP::QActive::recall(), QP::QEQueue

Definition at line 178 of file qf_defer.cpp.

◆ getPrio()

std::uint_fast8_t getPrio ( void ) const

inlinenoexcept

Get the priority of the active object.

Definition at line 251 of file qf.hpp.

◆ setPrio()

void setPrio ( std::uint_fast8_t const prio )

inline

Set the priority of the active object.

Definition at line 256 of file qf.hpp.

◆ setAttr()

void setAttr	(	std::uint32_t	attr1,
		void const *	attr2 = `nullptr`
	)

Generic setting of additional attributes (useful in QP ports)

◆ get_()

QEvt const * get_ ( void )

noexcept

Get an event from the event queue of an active object.

Description: The behavior of this function depends on the kernel used in the QF port. For built-in kernels (Vanilla or QK) the function can be called only when the queue is not empty, so it doesn't block. For a blocking kernel/OS the function can block and wait for delivery of an event.

Returns: A pointer to the received event. The returned pointer is guaranteed to be valid (can't be NULL).

Note: This function is used internally by a QF port to extract events from the event queue of an active object. This function depends on the event queue implementation and is sometimes customized in the QF port (file qf_port.hpp). Depending on the definition of the macro QACTIVE_EQUEUE_WAIT_(), the function might block the calling thread when no events are available.

Definition at line 313 of file qf_actq.cpp.

Friends And Related Function Documentation

◆ QF

friend class QF

friend

Definition at line 292 of file qf.hpp.

◆ QTimeEvt

friend class QTimeEvt

friend

Definition at line 293 of file qf.hpp.

◆ QTicker

friend class QTicker

friend

Definition at line 294 of file qf.hpp.

◆ QActiveDummy

friend class QActiveDummy ( void )

friend

Definition at line 305 of file qf.hpp.

Field Documentation

◆ m_prio

std::uint8_t m_prio

QF priority (1..QF_MAX_ACTIVE) of this active object.

Definition at line 185 of file qf.hpp.

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

Public Member Functions

Data Fields

Protected Member Functions

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ QActive()

Member Function Documentation

◆ start() [1/2]

◆ start() [2/2]

◆ stop()

◆ post_()

◆ postLIFO()

◆ unsubscribeAll()

◆ subscribe()

◆ unsubscribe()

◆ defer()

◆ recall()

◆ flushDeferred()

◆ getPrio()

◆ setPrio()

◆ setAttr()

◆ get_()

Friends And Related Function Documentation

◆ QF

◆ QTimeEvt

◆ QTicker

◆ QActiveDummy

Field Documentation

◆ m_prio