QF Active Object Framework namespace. More...

Classes
class	Attr
	Private attributes of the QF framework. More...

Typedefs
using	QCritStatus = std::uint_fast8_t
using	QSchedStatus = std::uint_fast8_t

Functions
void	init ()
	QF initialization.
void	stop ()
	Invoked by the application layer to stop the QF framework and return control to the OS/Kernel (used in some QF ports).
int_t	run ()
	Transfers control to QF to run the application.
void	onStartup ()
	Startup QF callback.
void	onCleanup ()
	Cleanup QF callback.
void	psInit (QSubscrList *const subscrSto, QSignal const maxSignal) noexcept
void	publish_ (QEvt const const e, void const const sender, std::uint_fast8_t const qsId) noexcept
std::uint_fast16_t	getQueueMin (std::uint_fast8_t const prio) noexcept
	This function returns the minimum of free entries of the given event queue.
void	tick (std::uint_fast8_t const tickRate, void const *const sender) noexcept
void	poolInit (void *const poolSto, std::uint_fast32_t const poolSize, std::uint_fast16_t const evtSize) noexcept
	Event pool initialization for dynamic allocation of events.
std::uint16_t	poolGetMaxBlockSize () noexcept
	Obtain the block size of any registered event pools.
std::uint16_t	getPoolUse (std::uint_fast8_t const poolNum) noexcept
std::uint16_t	getPoolFree (std::uint_fast8_t const poolNum) noexcept
std::uint16_t	getPoolMin (std::uint_fast8_t const poolNum) noexcept
	Obtain the minimum of free entries of the given event pool.
QEvt *	newX_ (std::uint_fast16_t const evtSize, std::uint_fast16_t const margin, QSignal const sig) noexcept
void	gc (QEvt const *const e) noexcept
	Recycle a mutable (mutable) event.
QEvt const *	newRef_ (QEvt const const e, QEvt const const evtRef) noexcept
void	deleteRef_ (QEvt const *const evtRef) noexcept
template<class evtT_, typename... Args>
evtT_ *	q_new (QSignal const sig, Args... args)
template<class evtT_, typename... Args>
evtT_ *	q_new_x (std::uint_fast16_t const margin, QSignal const sig, Args... args)
template<class evtT_>
void	q_new_ref (QP::QEvt const const e, evtT_ const &evtRef)
	Create a new reference of the current event e.
template<class evtT_>
void	q_delete_ref (evtT_ const *&evtRef)
	Delete a new reference of the current event e.
QEvt *	newXfromISR_ (std::uint_fast16_t const evtSize, std::uint_fast16_t const margin, QSignal const sig) noexcept
void	gcFromISR (QEvt const *e) noexcept
QCritStatus	critEntry (void)
void	critExit (QCritStatus critStat)
QSchedStatus	schedLock (uint_fast8_t const ceiling)
void	schedUnlock (QSchedStatus const prevCeil)

Variables
constexpr std::uint_fast16_t	NO_MARGIN {0xFFFFU}
	Special value of margin that causes asserting failure in case event allocation or event posting fails.
QF::Attr	priv_

Detailed Description

QF Active Object Framework namespace.

Typedef Documentation

◆ QCritStatus

using QP::QF::QCritStatus = std::uint_fast8_t

Definition at line 732 of file qs.hpp.

◆ QSchedStatus

using QP::QF::QSchedStatus = std::uint_fast8_t

Definition at line 737 of file qs.hpp.

Function Documentation

◆ init()

void QP::QF::init ( )

QF initialization.

Details
Initializes QF and must be called exactly once before any other QF function. Typically, QF_init() is called from main() even before initializing the Board Support Package (BSP).

Note: QF::init() clears the internal QF variables, so that the framework can start correctly even if the startup code fails to clear the uninitialized data (as is required by the C Standard).

Definition at line 64 of file qv.cpp.

◆ stop()

void QP::QF::stop ( )

Invoked by the application layer to stop the QF framework and return control to the OS/Kernel (used in some QF ports).

Details
This function stops the QF application. After calling this function, QF attempts to gracefully stop the application. This graceful shutdown might take some time to complete. The typical use of this function is for terminating the QF application to return back to the operating system or for handling fatal errors that require shutting down (and possibly re-setting) the system.

Attention: After calling QF_stop() the application must terminate and cannot continue. In particular, QF_stop() is not intended to be followed by a call to QF_init() to "resurrect" the application.

Definition at line 71 of file qv.cpp.

◆ run()

int_t QP::QF::run ( )

Transfers control to QF to run the application.

Details
QF::run() is typically called from your startup code after you initialize the QF and start at least one active object with QActive::start().

Returns: Typically in embedded systems QF::run() does not return, but in case QF runs on top of a General-Purpose OS (GPOS), QF::run() returns the error status with value 0 representing success.

Definition at line 77 of file qv.cpp.

◆ onStartup()

void QP::QF::onStartup ( )

Startup QF callback.

Details
The purpose of the QF_onStartup() callback is to configure and enable hardware interrupts. The callback is invoked from QF_run(), right before starting the underlying real-time kernel. By that time, the application is considered ready to receive and service interrupts.

This function is application-specific and is not implemented in QF, but rather in the Board Support Package (BSP) for the given application.

◆ onCleanup()

void QP::QF::onCleanup ( )

Cleanup QF callback.

Details
QP::QF::onCleanup() is called in some QF ports before QF returns to the underlying real-time kernel or operating system.

This function is strongly platform-specific and is not implemented in the QF, but either in the QF port or in the Board Support Package (BSP) for the given application. Some QF ports might not require implementing QF_onCleanup() at all, because many embedded applications don't have anything to exit to.

◆ psInit()

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

inlinenoexcept

Deprecated

Definition at line 768 of file qp.hpp.

◆ publish_()

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

inlinenoexcept

Deprecated

Definition at line 776 of file qp.hpp.

◆ getQueueMin()

std::uint_fast16_t QP::QF::getQueueMin ( std::uint_fast8_t const prio )

inlinenoexcept

This function returns the minimum of free entries of the given event queue.

Deprecated

Details
Queries the minimum of free ever present in the given event queue of an active object with priority prio, since the active object was started.

Note: This function is available only when the native QF event queue implementation is used. Requesting the queue minimum of an unused priority level raises an assertion in the QF. (A priority level becomes used in QF after the call to the QActive_register_() function.)

Parameters

[in] prio Priority of the active object, whose queue is queried

Returns: The minimum of free ever present in the given event queue of an active object with priority prio, since the active object was started.

Definition at line 784 of file qp.hpp.

◆ tick()

void QP::QF::tick	(	std::uint_fast8_t const	tickRate,
		void const *const	sender )

inlinenoexcept

Deprecated

Definition at line 793 of file qp.hpp.

◆ poolInit()

void QP::QF::poolInit	(	void *const	poolSto,
		std::uint_fast32_t const	poolSize,
		std::uint_fast16_t const	evtSize )

noexcept

Event pool initialization for dynamic allocation of events.

Details
This function initializes one event pool at a time and must be called exactly once for each event pool before the pool can be used.

Parameters

[in]	poolSto	pointer to the storage for the event pool
[in]	poolSize	size of the storage for the pool in bytes
[in]	evtSize	the block-size of the pool in bytes, which determines the maximum size of events that can be allocated from the pool.

You may initialize multiple event pools by issuing consecutive calls to QF::poolInit(). For correctness and to simplify the internal implementation, event pools must be initialized in ascending order of event-block size. The total number of initialized pools must not exceed QF_MAX_EPOOL. (If QF_MAX_EPOOL is configured to 0, the framework does not support mutable events.)

To ensure proper alignment of memory blocks within each pool buffer, the framework provides the helper macro QF_MPOOL_EL().

Note: The actual number of events available in a pool may be slightly less than the nominal value (poolSize / evtSize) due to internal block-alignment requirements. You can always determine the exact capacity of a pool by calling QF::getPoolFree() before any events have been allocated from it.

Usage

void main() {
    . . .
    // initialize Event Memory Pools...
    static QF_MPOOL_EL(QP::QEvt) smallPoolSto[20];
    QF::poolInit(smallPoolSto, sizeof(smallPoolSto), sizeof(smallPoolSto[0]));
 
    static QF_MPOOL_EL(MyMedEvt) mediumPoolSto[10];
    QF::poolInit(mediumPoolSto, sizeof(mediumPoolSto), sizeof(mediumPoolSto[0]));
 
    static QF_MPOOL_EL(MyLargeEvt) largePoolSto[5];
    QF::poolInit(largePoolSto, sizeof(largePoolSto), sizeof(largePoolSto[0]));
    . . .
}

Backward Traceability

DES_QP_START: Design view: QP/C++ Framework startup sequence.

Forward Traceability

Definition at line 51 of file qf_dyn.cpp.

◆ poolGetMaxBlockSize()

std::uint16_t QP::QF::poolGetMaxBlockSize ( )

noexcept

Obtain the block size of any registered event pools.

Details
Obtain the block size of any registered event pools

Definition at line 95 of file qf_dyn.cpp.

◆ getPoolUse()

std::uint16_t QP::QF::getPoolUse ( std::uint_fast8_t const poolNum )

noexcept

◆ getPoolFree()

std::uint16_t QP::QF::getPoolFree ( std::uint_fast8_t const poolNum )

noexcept

◆ getPoolMin()

std::uint16_t QP::QF::getPoolMin ( std::uint_fast8_t const poolNum )

noexcept

Obtain the minimum of free entries of the given event pool.

Details
This function obtains the minimum number of free blocks in the given event pool since this pool has been initialized by a call to QF_poolInit().

Parameters

[in] poolNum event pool ID in the range 1..max_pool, where max_pool is the number of event pools initialized with the function QF_poolInit().

Returns: the minimum number of unused blocks in the given event pool.

◆ newX_()

QEvt * QP::QF::newX_	(	std::uint_fast16_t const	evtSize,
		std::uint_fast16_t const	margin,
		QSignal const	sig )

noexcept

Definition at line 197 of file qf_dyn.cpp.

◆ gc()

void QP::QF::gc ( QEvt const *const e )

noexcept

Recycle a mutable (mutable) event.

Details
This function implements a simple garbage collector for the mutable events. Only mutable events are candidates for recycling. (A mutable event is one that is allocated from an event-pool, which is determined as non-zero QEvt_getPoolId_(e)) Next, the function decrements the reference counter of the event (e->refCtr_), and recycles the event only if the counter drops to zero (meaning that no more references are outstanding for this event). The mutable event is recycled by returning it to the pool from which it was originally allocated.

Parameters

[in] e pointer to the event to recycle

Note: QF invokes the garbage collector at all appropriate contexts, when an event can become garbage (automatic garbage collection), so the application code should have no need to call QF_gc() directly. The QF_gc() function is exposed only for special cases when your application sends mutable events to the "raw" thread-safe queues (see ::QEQueue). Such queues are processed outside of QF and the automatic garbage collection is NOT performed for these events. In this case you need to call QF_gc() explicitly.

Definition at line 276 of file qf_dyn.cpp.

◆ newRef_()

QEvt const * QP::QF::newRef_	(	QEvt const *const	e,
		QEvt const *const	evtRef )

noexcept

Definition at line 336 of file qf_dyn.cpp.

◆ deleteRef_()

void QP::QF::deleteRef_ ( QEvt const *const evtRef )

noexcept

Definition at line 378 of file qf_dyn.cpp.

◆ q_new()

template<class evtT_, typename... Args>

evtT_ * QP::QF::q_new	(	QSignal const	sig,
		Args...	args )

inline

Definition at line 842 of file qp.hpp.

◆ q_new_x()

template<class evtT_, typename... Args>

evtT_ * QP::QF::q_new_x	(	std::uint_fast16_t const	margin,
		QSignal const	sig,
		Args...	args )

inline

Definition at line 851 of file qp.hpp.

◆ q_new_ref()

template<class evtT_>

void QP::QF::q_new_ref	(	QP::QEvt const *const	e,
		evtT_ const *&	evtRef )

inline

Create a new reference of the current event e.

Details
The current event processed by an Active Object is available only for the duration of the run-to-completion (RTC) step. After that step, the current event is no longer available and the framework might recycle (garbage-collect) the event. The function template QP::QF::q_new_ref() explicitly creates a new reference to the current event that can be stored and used beyond the current RTC step, until the reference is explicitly recycled by means of the function template QP::QF::q_delete_ref().

See also: Q_NEW_REF()

Template Parameters

evtT_ event class (class name) of the event to allocate

Parameters

[in]	e	event to create a reference to
[in,out]	evtRef	reference object (of the type evtT_*

This function template does not return a value, but it modifies the evtRef parameter.

Usage
The example examples/posix-win32/defer illustrates the use of QP::QF::q_new_ref()

Definition at line 867 of file qp.hpp.

◆ q_delete_ref()

template<class evtT_>

void QP::QF::q_delete_ref ( evtT_ const *& evtRef )

inline

Delete a new reference of the current event e.

Details
Every event reference created with the function template QP::QF::q_new_ref() needs to be eventually deleted by means of the function template QP::QF::q_delete_ref() to avoid leaking the event.

See also: Q_DELETE_REF()

Template Parameters

evtT_ event class (class name) of the event to allocate

Parameters

[in,out] evtRef event reference to delete

This function template does not return a value, but it modifies the evtRef parameter.

Usage
The example examples/posix-win32/defer illustrates the use of QP::QF::q_delete_ref()

Definition at line 876 of file qp.hpp.

◆ newXfromISR_()

QEvt * QP::QF::newXfromISR_	(	std::uint_fast16_t const	evtSize,
		std::uint_fast16_t const	margin,
		QSignal const	sig )

noexcept

◆ gcFromISR()

void QP::QF::gcFromISR ( QEvt const * e )

noexcept

◆ critEntry()

QCritStatus QP::QF::critEntry ( void )

Definition at line 162 of file qutest.cpp.

◆ critExit()

void QP::QF::critExit ( QCritStatus critStat )

Definition at line 173 of file qutest.cpp.

◆ schedLock()

QSchedStatus QP::QF::schedLock ( uint_fast8_t const ceiling )

Definition at line 183 of file qutest.cpp.

◆ schedUnlock()

void QP::QF::schedUnlock ( QSchedStatus const prevCeil )

Definition at line 208 of file qutest.cpp.

Variable Documentation

◆ NO_MARGIN

std::uint_fast16_t QP::QF::NO_MARGIN {0xFFFFU}

constexpr

Special value of margin that causes asserting failure in case event allocation or event posting fails.

Definition at line 497 of file qp.hpp.

◆ priv_

Attr QP::QF::priv_

Definition at line 51 of file qf_qact.cpp.

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ QCritStatus

◆ QSchedStatus

Function Documentation

◆ init()

◆ stop()

◆ run()

◆ onStartup()

◆ onCleanup()

◆ psInit()

◆ publish_()

◆ getQueueMin()

◆ tick()

◆ poolInit()

◆ poolGetMaxBlockSize()

◆ getPoolUse()

◆ getPoolFree()

◆ getPoolMin()

◆ newX_()

◆ gc()

◆ newRef_()

◆ deleteRef_()

◆ q_new()

◆ q_new_x()

◆ q_new_ref()

◆ q_delete_ref()

◆ newXfromISR_()

◆ gcFromISR()

◆ critEntry()

◆ critExit()

◆ schedLock()

◆ schedUnlock()

Variable Documentation

◆ NO_MARGIN

◆ priv_