Active Object class (based on the QP::QHsm implementation strategy). More...

Inheritance diagram for QP::QActive:

Public Member Functions
void	init (void const *const e, std::uint_fast8_t const qsId) override
	Take the top-most initial transition in QActive (delegate to QP::QHsm).
void	dispatch (QEvt const *const e, std::uint_fast8_t const qsId) override
	Dispatch an event to QActive (delegate to QP::QHsm).
bool	isIn (QStateHandler const stateHndl) noexcept override
	Is-in-state query in QActive (delegate to QP::QHsm).
QStateHandler	getStateHandler () const noexcept override
	Get current state-handler in QActive (delegate to QP::QHsm).
QStateHandler	childState (QStateHandler const parentHandler) noexcept
void	setAttr (std::uint32_t attr1, void const *attr2=nullptr)
	Generic setting of additional attributes (defined in some QP ports).
void	start (QPrioSpec const prioSpec, QEvtPtr const qSto, std::uint_fast16_t const qLen, void const stkSto, std::uint_fast16_t const stkSize, void const *const par=nullptr)
	Starts execution of an active object and registers the object with the framework.
void	stop ()
	Stops execution of an active object and removes it from the framework's supervision.
void	register_ () noexcept
	Register this active object to be managed by the framework.
void	unregister_ () noexcept
	Un-register the active object from the framework.
void	post_ (QEvt const const e, 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.
bool	postx_ (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.
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 (QSignal const sig) const noexcept
	Subscribes for delivery of signal sig to the active object.
void	unsubscribe (QSignal 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::uint16_t	flushDeferred (QEQueue *const eq, std::uint_fast16_t const num=0xFFFFU) const noexcept
	Flush the specified deferred queue eq.
std::uint8_t	getPrio () const noexcept
QACTIVE_THREAD_TYPE const &	getThread () const &
QACTIVE_THREAD_TYPE const &	getThread () const &&=delete
void	setThread (QACTIVE_THREAD_TYPE const &thr) noexcept
QACTIVE_OS_OBJ_TYPE const &	getOsObject () const &
QACTIVE_OS_OBJ_TYPE const &	getOsObject () const &&=delete
virtual bool	postFromISR (QEvt const const e, std::uint_fast16_t const margin, void const par, void const *const sender) noexcept
	The "FromISR" variant used in the QP port to "FreeRTOS" .
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 std::uint16_t	getQueueUse (std::uint_fast8_t const prio) noexcept
static std::uint16_t	getQueueFree (std::uint_fast8_t const prio) noexcept
static std::uint16_t	getQueueMin (std::uint_fast8_t const prio) noexcept
static void	psInit (QSubscrList *const subscrSto, QSignal const maxSignal) noexcept
	Initializes the publish-subscribe facility for the application.
static void	publish_ (QEvt const const e, void const const sender, std::uint_fast8_t const qsId) noexcept
	Publish event to all subscribers of a given signal e->sig.
static void	evtLoop_ (QActive *act)
	Event loop thread routine for executing an active object act (defined some in QP ports).
static QActive *	fromRegistry (std::uint_fast8_t const prio)
static void	publishFromISR (QEvt const const e, void const par, void const *const sender) noexcept
	The "FromISR" variant used in the QP port to "FreeRTOS" .
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
	QActive (QStateHandler const initial) noexcept
	QActive constructor (abstract base class).
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
void	postFIFO_ (QEvt const const e, void const const sender)

Static Private Member Functions
static void	multicast_ (QPSet const subscrSet, QEvt const const e, void const *const sender)

Private Attributes
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.
QACTIVE_THREAD_TYPE	m_thread
	Port-dependent representation of the thread of the active object.
QACTIVE_OS_OBJ_TYPE	m_osObject
	Port-dependent per-thread object.
QACTIVE_EQUEUE_TYPE	m_eQueue
	Port-dependent event-queue type (often QP::QEQueue).

Friends
class	QTimeEvt
class	QTicker
class	QXThread
class	QXMutex
class	QXSemaphore
class	QMActive
class	QActiveDummy
class	QK
class	QXK
class	QS
void	QF::init ()
void	QF::stop ()
int_t	QF::run ()
void	QF::onStartup ()
void	QF::onCleanup ()

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

Active Object class (based on the QP::QHsm implementation strategy).

Details

Active objects are encapsulated tasks (each containing an event queue and a state machine) 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 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 slightly slower than in the QMsm-style implementation strategy.

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

See also

Usage

The following example illustrates how to derive an active object from QP::QActive.

class Philo : public QP::QActive { // <=== inherit QP::QActive
private:
    QP::QTimeEvt m_timeEvt;
    std::uint8_t m_id;
 
public:
    static Philo inst[N_PHILO];
 
public:
    Philo();
 
protected:
    Q_STATE_DECL(initial);
    Q_STATE_DECL(thinking);
    Q_STATE_DECL(hungry);
    Q_STATE_DECL(eating);
};

Backward Traceability

[SDS_QP_QActive] Design view: QP::QActive Active Object class.

Forward Traceability

[MISRA_QP_DVR_PCLP_1801] Base class has a destructor that is not public virtual; public override or protected non-virtual
[MISRA_QP_DVR_PCLP_1985] move-only or copy-enabled public base xxx of class lacks a protected non-virtual destructor
[QP::QF::getQueueMin()] This function returns the minimum of free entries of the given event queue

Definition at line 501 of file qp.hpp.

Constructor & Destructor Documentation

◆ QActive()

QP::QActive::QActive ( QStateHandler const initial )

explicitprotectednoexcept

QActive constructor (abstract base class).

Parameters

[in] initial pointer to the top-most initial state-handler function in the derived active object

Usage

Blinky::Blinky()
  : QP::QActive(Q_STATE_CAST(&initial)) // ctor of the superclass <---
    . . . // call ctor of other members
{}

See also

QHsm::QHsm_ctor()

Forward Traceability

Definition at line 55 of file qf_qact.cpp.

Member Function Documentation

◆ init() [1/2]

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

overridevirtual

Take the top-most initial transition in QActive (delegate to QP::QHsm).

Forward Traceability

[MISRA_QP_DVR_MP2_R8_2_5] Rule 8.2.5(Required): reinterpret_cast<> shall not be used
[MISRA_QP_DVR_PCLP_1933] call to unqualified virtual function from non-static member function

Implements QP::QAsm.

Reimplemented in QP::QActiveDummy, QP::QMActive, QP::QTicker, and QP::QXThread.

Definition at line 134 of file qf_qact.cpp.

◆ dispatch()

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

overridevirtual

Dispatch an event to QActive (delegate to QP::QHsm).

Forward Traceability

[MISRA_QP_DVR_MP2_R8_2_5] Rule 8.2.5(Required): reinterpret_cast<> shall not be used

Implements QP::QAsm.

Reimplemented in QP::QActiveDummy, QP::QMActive, QP::QTicker, and QP::QXThread.

Definition at line 142 of file qf_qact.cpp.

◆ isIn()

bool QP::QActive::isIn ( QStateHandler const stateHndl )

overridevirtualnoexcept

Is-in-state query in QActive (delegate to QP::QHsm).

Forward Traceability

[MISRA_QP_DVR_MP2_R8_2_5] Rule 8.2.5(Required): reinterpret_cast<> shall not be used

Implements QP::QAsm.

Reimplemented in QP::QMActive.

Definition at line 150 of file qf_qact.cpp.

◆ getStateHandler()

QStateHandler QP::QActive::getStateHandler ( ) const

overridevirtualnoexcept

Get current state-handler in QActive (delegate to QP::QHsm).

Forward Traceability

[MISRA_QP_DVR_MP2_R8_2_5] Rule 8.2.5(Required): reinterpret_cast<> shall not be used

Implements QP::QAsm.

Reimplemented in QP::QActiveDummy, and QP::QMActive.

Definition at line 165 of file qf_qact.cpp.

◆ childState()

QStateHandler QP::QActive::childState ( QStateHandler const parentHandler )

noexcept

Definition at line 155 of file qf_qact.cpp.

◆ setAttr()

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

Generic setting of additional attributes (defined in some QP ports).

Forward Traceability

◆ start()

void QP::QActive::start	(	QPrioSpec const	prioSpec,
		QEvtPtr *const	qSto,
		std::uint_fast16_t const	qLen,
		void *const	stkSto,
		std::uint_fast16_t const	stkSize,
		void const *const	par = nullptr )

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

Details

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

Parameters

[in]	prioSpec	priority specification for the AO (See 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 NULL)
[in]	stkSize	stack size [bytes]
[in]	par	initialization parameter (optional)

Usage

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

#include "qpcpp.hpp"
 
int main() {
    QP::QF::init(); // initialize the framework and the underlying RT kernel
    BSP::init();    // initialize the Board Support Package
    . . .
    // instantiate and start the active objects...
    static QP::QEvt const *blinkyQueueSto[10];
    APP::AO_Blinky->start(
        1U,                         // QP prio. of the AO
        blinkyQueueSto,              // event queue storage
        Q_DIM(blinkyQueueSto),       // queue length [events]
        nullptr, 0U);                // no stack storage
    . . .
    return QP::QF::run(); // run the QF application
}

Forward Traceability

[MISRA_QP_DVR_MP2_R10_1_1] Rule 10.1.1(Advisory): The target type of a pointer or lvalue reference parameter should be const-qualified appropriately
[MISRA_QP_DVR_PCLP_1933] call to unqualified virtual function from non-static member function

Definition at line 174 of file qv.cpp.

◆ stop()

void QP::QActive::stop ( )

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.

Forward Traceability

Definition at line 277 of file qutest.cpp.

◆ register_()

void QP::QActive::register_ ( )

noexcept

Register this active object to be managed by the framework.

Details

This function adds a given active object to the active objects managed by the QF framework. It should not be called by the application directly, only through the function QActive::start().

Forward Traceability

Definition at line 68 of file qf_qact.cpp.

◆ unregister_()

void QP::QActive::unregister_ ( )

noexcept

Un-register the active object from the framework.

Details

This function un-registers a given active object from the active objects managed by the QF framework. It should not be called by the QP ports.

Note: The active object that is removed from the framework can no longer participate in any event exchange.

Forward Traceability

Definition at line 116 of file qf_qact.cpp.

◆ post_()

void QP::QActive::post_	(	QEvt const *const	e,
		void const *const	sender )

inlinenoexcept

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

Details

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

Parameters

[in]	e	pointer to the event to be posted
[in]	sender	pointer to a sender object (used in QS only)

Attention: This operation should be called via the macros POST() and POST_X(). This is because the last parameter sender might be defined/provided only in the Spy build configuration (see Q_SPY). The macros ignore the sender parameter outside the Spy configuration, so the same code builds correctly in all configurations.

Note: This function delegates to QP::QActive::postx_() with the margin_ parameter set to QF::NO_MARGIN

Usage

extern QP::QActive * const AO_Table;
. . .
Q_STATE_DEF(Philo, hungry) {
    QP::QState status;
    switch (e->sig) {
        case Q_ENTRY_SIG: {
            TableEvt const *pe = QP::QF::q_new<TableEvt>(HUNGRY_SIG, m_id);
            AO_Table->POST(pe, this); // <===
            status = Q_RET_HANDLED;
            break;
        }
        . . .
    }
    return status;
}

Forward Traceability

Definition at line 546 of file qp.hpp.

◆ postx_()

bool QP::QActive::postx_	(	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.

Details

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)

Return values

true	(Success) if the posting succeeded (with the provided margin)
false	(Failure) when the posting fails

Attention: This operation should be called via the macros POST() and POST_X(). This is because the last parameter sender might be defined/provided only in the Spy build configuration (see Q_SPY). The macros ignore the sender parameter outside the Spy configuration, so the same code builds correctly in all configurations.

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

Usage

extern QP::QActive * const AO_Table;
. . .
Q_STATE_DEF(Philo, hungry) {
    QP::QState status_;
    switch (e->sig) {
        case Q_ENTRY_SIG: {
            TableEvt const *pe = QP::QF::q_new<TableEvt>(HUNGRY_SIG, m_id);
            AO_Table->POST_X(pe, 5U, this); // <===
            status_ = Q_RET_HANDLED;
            break;
        }
        . . .
    }
    return status_;
}

Forward Traceability

Definition at line 49 of file qf_actq.cpp.

◆ postLIFO()

void QP::QActive::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.

Details

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

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

See also

QP::QActive::post_()

Forward Traceability

Definition at line 120 of file qf_actq.cpp.

◆ get_()

QEvt const * QP::QActive::get_ ( )

noexceptinternal

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

Details

The behavior of this function depends on the kernel used in the QF port. For built-in kernels (QV 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.

Return values

evt	Pointer to the received event. The returned pointer is guaranteed to be valid (can't be NULL).

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

Forward Traceability

Definition at line 191 of file qf_actq.cpp.

◆ getQueueUse()

std::uint16_t QP::QActive::getQueueUse ( std::uint_fast8_t const prio )

staticnoexcept

Definition at line 310 of file qf_actq.cpp.

◆ getQueueFree()

std::uint16_t QP::QActive::getQueueFree ( std::uint_fast8_t const prio )

staticnoexcept

Definition at line 343 of file qf_actq.cpp.

◆ getQueueMin()

std::uint16_t QP::QActive::getQueueMin ( std::uint_fast8_t const prio )

staticnoexcept

Definition at line 362 of file qf_actq.cpp.

◆ psInit()

void QP::QActive::psInit	(	QSubscrList *const	subscrSto,
		QSignal const	maxSignal )

staticnoexcept

Initializes the publish-subscribe facility for the application.

Details

This function must be called during system initialization, before any Active Object subscribes to signals or before any events are published. It configures the global subscription list used by the QP Framework's publish-subscribe mechanism.

Parameters

[in]	subscrSto	Pointer to the storage for the subscription list. The storage must provide one entry for every publishable signal up to and including maxSignal.
[in]	maxSignal	The highest signal identifier that may be published at runtime. This value determines the size of the subscription list and must cover all signals that any Active Object may subscribe to.

Note: The function must be called exactly once during system startup before any Active Object subscribes to signals or before any events are published.

Usage

void BSP::init(void const * const arg) {
    . . .
    // initialize publish-subscribe
    static std::array<QP::QSubscrList, MAX_PUB_SIG> subscrSto;
    QActive::psInit(&subscrSto[0], subscrSto.size()); // <===
    . . .
}

Backward Traceability

[SDS_QP_START] Design view: QP/C++ Framework startup sequence.

Forward Traceability

Definition at line 51 of file qf_ps.cpp.

◆ publish_()

void QP::QActive::publish_	(	QEvt const *const	e,
		void const *const	sender,
		std::uint_fast8_t const	qsId )

staticnoexcept

Publish event to all subscribers of a given signal e->sig.

Details

This function posts (using the FIFO policy) the event e to all active objects that have subscribed to the signal e->sig, which is called multicasting. The multicasting performed in this function is very efficient based on reference-counting inside the published event (zero-copy event multicasting). This function is designed to be callable from any part of the system, including ISRs, device drivers, and active objects.

Note: To avoid any unexpected re-ordering of events posted into AO queues, the event multicasting is performed with scheduler locked. However, the scheduler is locked only up to the priority level of the highest-priority subscriber, so any AOs of even higher priority, which did not subscribe to this event, are not affected.

Attention: This operation is typically used via macro PUBLISH(). This is because the last parameter qsId might be defined/provided only in the Spy build configuration (see Q_SPY). The macro ignores the qsId parameter outside the Spy configuration, so the same code builds correctly in all configurations.

Usage

Q_STATE_DEF(Philo, eating) {
    QP::QState status_;
    switch (e->sig) {
        . . .
        case Q_EXIT_SIG: {
            TableEvt const *pe = QP::QF::q_new<TableEvt>(DONE_SIG, m_id);
            QP::QActive::PUBLISH(pe, this); // <===
            status_ = Q_RET_HANDLED;
            break;
        }
        . . .
    }
    return status_;
}

Forward Traceability

Definition at line 76 of file qf_ps.cpp.

◆ subscribe()

void QP::QActive::subscribe ( QSignal const sig ) const

noexcept

Subscribes for delivery of signal sig to the active object.

Details

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

Usage

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

Q_STATE_DEF(Philo, initial) {
    Q_UNUSED_PAR(e);
    . . .
    subscribe(EAT_SIG);   // <===
    subscribe(TEST_SIG);  // <===
    . . .
    return tran(&thinking);
}

Forward Traceability

Definition at line 190 of file qf_ps.cpp.

◆ unsubscribe()

void QP::QActive::unsubscribe ( QSignal const sig ) const

noexcept

Unsubscribes from the delivery of signal sig to the active object.

Details

This function is part of the Publish-Subscribe event delivery mechanism available in QF. Unsubscribing 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 already be in the queue or just about to be posted, and the unsubscribe operation will not flush such events.; Unsubscribing from a signal that has never been subscribed in the first place is considered an error, and QF will raise an assertion.

Forward Traceability

Definition at line 221 of file qf_ps.cpp.

◆ unsubscribeAll()

void QP::QActive::unsubscribeAll ( ) const

noexcept

Unsubscribes from the delivery of all signals to the active object.

Details

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 unsubscribing from all events. The events might already be in the queue or just about to be posted, and the unsubscribe operation will not flush such events. Also, the alternative event-delivery mechanisms, such as direct event posting or time events, can still be delivered to the event queue of the active object.

Forward Traceability

Definition at line 250 of file qf_ps.cpp.

◆ defer()

bool QP::QActive::defer	(	QEQueue *const	eq,
		QEvt const *const	e ) const

noexcept

Defer an event to a given separate event queue.

Details

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.

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

Parameters

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

Return values

true	(Success) when the event could be deferred
false	(Failure) if event deferral failed due to overflowing the queue

Forward Traceability

[SSM_QP_ASR_413] Application-level state machines must not internally poll or block for events.
[SSM_QP_ASR_417] Application-level state machines must not use the current event after the dispatch.

Definition at line 48 of file qf_defer.cpp.

◆ recall()

bool QP::QActive::recall ( QEQueue *const eq )

noexcept

Recall a deferred event from a given event queue.

Details

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.

Return values

true	If an event has been recalled
false	Otherwise

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

Forward Traceability

Definition at line 81 of file qf_defer.cpp.

◆ flushDeferred()

std::uint16_t QP::QActive::flushDeferred	(	QEQueue *const	eq,
		std::uint_fast16_t const	num = 0xFFFFU ) const

noexcept

Flush the specified deferred queue eq.

Details

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.
[in]	num	number of events to flush (note can be a big number, like 0xFFFFU to flush all events)

Return values

number The number of events flushed from the queue.

Forward Traceability

Definition at line 135 of file qf_defer.cpp.

◆ getPrio()

std::uint8_t QP::QActive::getPrio ( ) const

inlinenoexcept

Definition at line 580 of file qp.hpp.

◆ evtLoop_()

void QP::QActive::evtLoop_ ( QActive * act )

static

Event loop thread routine for executing an active object act (defined some in QP ports).

Forward Traceability

◆ fromRegistry()

QActive * QP::QActive::fromRegistry ( std::uint_fast8_t const prio )

static

Definition at line 160 of file qf_qact.cpp.

◆ getThread()

QACTIVE_THREAD_TYPE const & QP::QActive::getThread ( ) const &

inline

Definition at line 587 of file qp.hpp.

◆ setThread()

void QP::QActive::setThread ( QACTIVE_THREAD_TYPE const & thr )

inlinenoexcept

Definition at line 594 of file qp.hpp.

◆ getOsObject()

QACTIVE_OS_OBJ_TYPE const & QP::QActive::getOsObject ( ) const &

inline

Definition at line 600 of file qp.hpp.

◆ postFIFO_()

void QP::QActive::postFIFO_	(	QEvt const *const	e,
		void const *const	sender )

private

Definition at line 255 of file qf_actq.cpp.

◆ multicast_()

void QP::QActive::multicast_	(	QPSet *const	subscrSet,
		QEvt const *const	e,
		void const *const	sender )

staticprivate

Definition at line 132 of file qf_ps.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.

Reimplemented in QP::QMActive, QP::QTicker, and QP::QXThread.

Definition at line 218 of file qf_act.cpp.

◆ QTimeEvt

friend class QTimeEvt

friend

Definition at line 632 of file qp.hpp.

◆ QTicker

friend class QTicker

friend

Definition at line 633 of file qp.hpp.

◆ QXThread

friend class QXThread

friend

Definition at line 634 of file qp.hpp.

◆ QXMutex

friend class QXMutex

friend

Definition at line 635 of file qp.hpp.

◆ QXSemaphore

friend class QXSemaphore

friend

Definition at line 636 of file qp.hpp.

◆ QMActive

friend class QMActive

friend

Definition at line 637 of file qp.hpp.

◆ QActiveDummy

friend class QActiveDummy

friend

Definition at line 638 of file qp.hpp.

◆ QK

friend class QK

friend

Definition at line 639 of file qp.hpp.

◆ QXK

friend class QXK

friend

Definition at line 640 of file qp.hpp.

◆ QS

friend class QS

friend

Definition at line 641 of file qp.hpp.

Member Data Documentation

◆ m_prio

std::uint8_t QP::QActive::m_prio

private

QF-priority [1..QF_MAX_ACTIVE] of this AO.

See also

QP::QPrioSpec

Definition at line 503 of file qp.hpp.

◆ m_pthre

std::uint8_t QP::QActive::m_pthre

private

Preemption-threshold [1..QF_MAX_ACTIVE] of this AO.

See also

QP::QPrioSpec

Definition at line 504 of file qp.hpp.

◆ m_thread

QACTIVE_THREAD_TYPE QP::QActive::m_thread

private

Port-dependent representation of the thread of the active object.

Details

This data might be used in various ways, depending on the QF port. In some ports me->thread is used store the thread handle. In other ports me->m_thread can be a pointer to the Thread-Local-Storage (TLS).

Definition at line 507 of file qp.hpp.

◆ m_osObject

QACTIVE_OS_OBJ_TYPE QP::QActive::m_osObject

private

Port-dependent per-thread object.

Details

This data might be used in various ways, depending on the QF port. In some ports me->osObject is used to block the calling thread when the native QF queue is empty. In other QF ports the OS-dependent object might be used differently.

Definition at line 511 of file qp.hpp.

◆ m_eQueue

QACTIVE_EQUEUE_TYPE QP::QActive::m_eQueue

private

Port-dependent event-queue type (often QP::QEQueue).

Details

The type of the queue depends on the underlying operating system or a kernel. Many kernels support "message queues" that can be adapted to deliver QF events to the active object. Alternatively, QF provides a native event queue implementation that can be used as well.

Note: The native QF event queue is configured by defining the macro QP::QACTIVE_EQUEUE_TYPE as QP::QEQueue.

Definition at line 515 of file qp.hpp.

Public Member Functions

Static Public Member Functions

Protected Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ QActive()

Member Function Documentation

◆ init() [1/2]

◆ dispatch()

◆ isIn()

◆ getStateHandler()

◆ childState()

◆ setAttr()

◆ start()

◆ stop()

◆ register_()

◆ unregister_()

◆ post_()

◆ postx_()

◆ postLIFO()

◆ get_()

◆ getQueueUse()

◆ getQueueFree()

◆ getQueueMin()

◆ psInit()

◆ publish_()

◆ subscribe()

◆ unsubscribe()

◆ unsubscribeAll()

◆ defer()

◆ recall()

◆ flushDeferred()

◆ getPrio()

◆ evtLoop_()

◆ fromRegistry()

◆ getThread()

◆ setThread()

◆ getOsObject()

◆ postFIFO_()

◆ multicast_()

◆ init() [2/2]

Friends And Related Symbol Documentation

◆ QTimeEvt

◆ QTicker

◆ QXThread

◆ QXMutex

◆ QXSemaphore

◆ QMActive

◆ QActiveDummy

◆ QK

◆ QXK

◆ QS

Member Data Documentation

◆ m_prio

◆ m_pthre

◆ m_thread

◆ m_osObject

◆ m_eQueue