QP/C++  7.4.0-rc.1
Real-Time Embedded Framework
Loading...
Searching...
No Matches
QP::QF Namespace Reference

QF Active Object Framework. More...

Classes

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

Functions

void init ()
 
void stop ()
 
int_t run ()
 
void onStartup ()
 
void onCleanup ()
 
void psInit (QSubscrList *const subscrSto, enum_t const maxSignal) noexcept
 
void publish_ (QEvt const *const e, void const *const sender, std::uint_fast8_t const qsId) noexcept
 
void tick (std::uint_fast8_t const tickRate, void const *const sender) noexcept
 
std::uint_fast16_t getQueueMin (std::uint_fast8_t const prio) noexcept
 
void poolInit (void *const poolSto, std::uint_fast32_t const poolSize, std::uint_fast16_t const evtSize) noexcept
 
std::uint_fast16_t poolGetMaxBlockSize () noexcept
 
std::uint_fast16_t getPoolMin (std::uint_fast8_t const poolNum) noexcept
 
QEvtnewX_ (std::uint_fast16_t const evtSize, std::uint_fast16_t const margin, enum_t const sig) noexcept
 
void gc (QEvt const *const e) noexcept
 
QEvt const * newRef_ (QEvt const *const e, QEvt const *const evtRef) noexcept
 
void deleteRef_ (QEvt const *const evtRef) noexcept
 
template<class evtT_ >
evtT_ * q_new (enum_t const sig)
 
template<class evtT_ >
evtT_ * q_new_x (std::uint_fast16_t const margin, enum_t const sig)
 
template<class evtT_ >
void q_new_ref (QP::QEvt const *const e, evtT_ const *&evtRef)
 
template<class evtT_ >
void q_delete_ref (evtT_ const *&evtRef)
 
QEvtnewXfromISR_ (std::uint_fast16_t const evtSize, std::uint_fast16_t const margin, enum_t const sig) noexcept
 
void gcFromISR (QEvt const *e) noexcept
 
void bzero_ (void *const start, std::uint_fast16_t const len) noexcept
 

Variables

constexpr std::uint_fast16_t NO_MARGIN {0xFFFFU}
 
QF::Attr priv_
 

Detailed Description

QF Active Object Framework.

Function Documentation

◆ init()

void QP::QF::init ( void )

QF initialization

Description
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).
Traceability
  • DVR-QP-MC4-R11_08

Definition at line 369 of file qk.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).

Description
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 391 of file qk.cpp.

◆ run()

int_t QP::QF::run ( )

Transfers control to QF to run the application.

Description
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 397 of file qk.cpp.

◆ onStartup()

void QP::QF::onStartup ( )

Startup QF callback.

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

Description
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,
enum_t const maxSignal )
inlinenoexcept
Deprecated

Definition at line 1062 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 1071 of file qp.hpp.

◆ tick()

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

Definition at line 1081 of file qp.hpp.

◆ getQueueMin()

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

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

Description
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]prioPriority 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 1090 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.

Description
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]poolStopointer to the storage for the event pool
[in]poolSizesize of the storage for the pool in bytes
[in]evtSizethe block-size of the pool in bytes, which determines the maximum size of events that can be allocated from the pool.
Precondition qf_dyn:200
  • the number of event-pools initialized so far must not exceed the maximum QF_MAX_EPOOL
Precondition qf_dyn:201
  • except the first event-pool 0, the event-size of the previously initialized event pool must not exceed the next event size.

You might initialize many event pools by making many consecutive calls to the QF_poolInit() function. However, for the simplicity of the internal implementation, you must initialize event pools in the ascending order of the event size.

Remarks
Many RTOSes provide fixed block-size heaps, a.k.a. memory pools that can be adapted for QF event-pools. In case the pools from the RTOS are not used, QF provides a native memory pool implementation (QMPool). The macro QF_EPOOL_TYPE_ determines the type of event pool used by a particular QF port.
Note
The actual number of events available in the pool might be actually less than (poolSize / evtSize) due to the internal alignment of the blocks that the pool might perform. You can always check the capacity of the pool by calling QF_getPoolMin().
The dynamic allocation of events is optional, meaning that you might choose not to use mutable events. In that case calling QF_poolInit() and using up memory for the memory blocks is unnecessary.

Definition at line 73 of file qf_dyn.cpp.

◆ poolGetMaxBlockSize()

std::uint_fast16_t QP::QF::poolGetMaxBlockSize ( )
noexcept

Obtain the block size of any registered event pools.

Description
Obtain the block size of any registered event pools

Definition at line 112 of file qf_dyn.cpp.

◆ getPoolMin()

std::uint_fast16_t QP::QF::getPoolMin ( std::uint_fast8_t const poolNum)
noexcept

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

Description
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]poolNumevent 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.
Precondition qf_dyn:400
  • the poolNum must be in range

Definition at line 125 of file qf_dyn.cpp.

◆ newX_()

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

Internal QF implementation of creating new mutable event.

Description
Allocates an event dynamically from one of the QF event pools.
Parameters
[in]evtSizethe size (in bytes) of the event to allocate
[in]marginthe number of un-allocated events still available in a given event pool after the allocation completes. The special value QF::NO_MARGIN means that this function will assert if allocation fails.
[in]sigthe signal to be assigned to the allocated event
Returns
Pointer to the newly allocated event. This pointer can be NULL only if margin != QF::NO_MARGIN and the event cannot be allocated with the specified margin still available in the given pool.
Precondition qf_dyn:300
  • the event size must fit one of the initialized event pools
Note
The internal QF function QF_newX_() raises an assertion when the margin parameter is QF::NO_MARGIN and allocation of the event turns out to be impossible due to event pool depletion, or incorrect (too big) size of the requested event.
The application code should not call this function directly. The only allowed use is thorough the QP::QF::q_new() or QP::QF::q_new_x() function templates.

Definition at line 143 of file qf_dyn.cpp.

◆ gc()

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

Recycle a mutable (mutable) event

Description
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]epointer 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.
Traceability
  • DVR-QP-MC4-R11_08

Definition at line 222 of file qf_dyn.cpp.

◆ newRef_()

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

Definition at line 278 of file qf_dyn.cpp.

◆ deleteRef_()

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

Definition at line 313 of file qf_dyn.cpp.

◆ q_new()

template<class evtT_ >
evtT_ * QP::QF::q_new ( enum_t const sig)
inline

Function template to allocate a dynamic event and asserting successful allocation.

Description
This function template allocates a mutable (dynamic) event and asserts that the allocation was successful. The caller of this template does not need to check for validity of the returned event pointer. However, the QP Application is responsible for sizing the event pools adequately. (This is part of event-delivery guarantee.)
See also
Q_NEW()
Template Parameters
evtT_event class (class name) of the event to allocate
Parameters
[in]sigsignal to assign to the newly allocated event
Returns
A valid event pointer of the type evtT_*.
Note
If QEVT_PAR_INIT is defined, the q_new<evtT> template becomes variadic and takes all the arguments needed by the init() member function of the event class being allocated. This enables initialization of the event at allocation (RAII).
Usage
The following example illustrates non-variadic version of the q_new<evtT> template (when QEVT_PAR_INIT is NOT defined):
// event without parameters
QP::QEvt const *myEvt = QP::QF::q_new<QP::QEvt>(APP::MY_SIG); // <==
// post or publish the event... (no need to check for nullptr)
// event with parameter(s) (event parameter(s) initialized separately)
APP::KeypressEvt *kevt = QP::QF::q_new<APP::KeypressEvt>(APP::KEYPRESS_SIG); // <==
kevt->keyId = keyId; // initialize event parameters (no need to check for nullptr)
// post or publish the event...
Event class.
Definition qp.hpp:137
evtT_ * q_new(enum_t const sig)
Definition qp.hpp:1137
The following example illustrates variadic version of the q_new<evtT> template (when QEVT_PAR_INIT IS defined):
// event without parameters (note QP::QEvt::DYNAMIC dummy parameter)
QP::QEvt const *myEvt =
// post or publish the event... (no need to check for nullptr)
// event with parameters
namespace APP {
struct KeypressEvt : public QP::QEvt { <=== inherit QP::QEvt
// event parameters follow...
std::uint8_t keyId; // ID of the key pressed
// when QEVT_PAR_INIT is defined, the "ctor" must be provided
#ifdef QEVT_PAR_INIT
void init(std::uint8_t id) {
keyId = id;
}
void init() { // init() might be overloaded
keyId = 123;
}
#endif // QEVT_PAR_INIT
} KeypressEvt;
} // namespace
// event with parameters (keyId passed to KeypressEvt::init())
APP::KeypressEvt const *kevt = QP::QF::q_new<APP::KeypressEvt>(APP::KEYPRESS_SIG, keyId); // <==
// post or publish the event... (no need to check for nullptr)
@ DYNAMIC
Definition qp.hpp:145
void init()
Definition qk.cpp:369

Definition at line 1137 of file qp.hpp.

◆ q_new_x()

template<class evtT_ >
evtT_ * QP::QF::q_new_x ( std::uint_fast16_t const margin,
enum_t const sig )
inline

Function template to allocate a dynamic event without asserting successful allocation.

Description
This template allocates a mutable (dynamic) event, but only if the corresponding event pool has at least margin of free events left. If the event pool has insufficient number of events left, the template returns nullptr. The caller of this template is responsible for checking the returned event pointer for nullptr.
See also
Q_NEW_X()
Template Parameters
evtT_event class (class name) of the event to allocate
Parameters
[in]marginnumber of events that must remain available in the given pool after this allocation. The special value QF_NO_MARGIN causes asserting failure in case event allocation fails.
[in]sigsignal to assign to the newly allocated event
Returns
An event pointer of the type evtT_* or nullptr if the event cannot be allocated with the specified margin of events still left in the event pool.
Note
If QEVT_PAR_INIT is defined, the q_new_x<evtT> template becomes variadic and takes all the arguments needed by the init() of the event class being allocated. This enables initialization of the event at allocation (RAII).
Usage
The following example illustrates non-variadic version of the q_new_x<evtT> template (when QEVT_PAR_INIT is NOT defined):
// event without parameters
QP::QEvt const *myEvt = QP::QF::q_new_x<QP::QEvt>(5U, APP::MY_SIG); // <== (margin == 5U)
if (myEvt) { // check the event pointer!
// post or publish the event...
}
// event with parameter(s) (event parameter(s) initialized separately)
APP::KeypressEvt *kevt = QP::QF::q_new_x<APP::KeypressEvt>(10U, APP::KEYPRESS_SIG); // <===
if (kevt) { // check the event pointer!
kevt->keyId = keyId; // initialize event parameters
// post or publish the event...
}
evtT_ * q_new_x(std::uint_fast16_t const margin, enum_t const sig)
Definition qp.hpp:1160
The following example illustrates variadic version of the q_new_x<evtT> template (when QEVT_PAR_INIT IS defined):
// event without parameters (note QP::QEvt::DYNAMIC dummy parameter)
QP::QEvt const *myEvt =
QP::QF::q_new_x<QP::QEvt>(APP::MY_SIG, 5U, QP::QEvt::DYNAMIC); // <== (margin == 5U)
if (myEvt) { // check the event pointer!
// post or publish the event...
}
// event with parameters
namespace APP {
struct KeypressEvt : public QP::QEvt { <=== inherit QP::QEvt
// event parameters follow...
std::uint8_t keyId; // ID of the key pressed
// when QEVT_PAR_INIT is defined, the "ctor" must be provided
#ifdef QEVT_PAR_INIT
void init(std::uint8_t id) {
keyId = id;
}
void init() { // init() might be overloaded
keyId = 123;
}
#endif // QEVT_PAR_INIT
} KeypressEvt;
} // namespace
// event with parameters (keyId passed to KeypressEvt::init())
APP::KeypressEvt const *kevt =
QP::QF::q_new_x<APP::KeypressEvt>(10U, APP::KEYPRESS_SIG, keyId); // <==
if (kevt) { // check the event pointer!
// post or publish the event...
}
Usage
The example examples/posix-win32/reminder2 illustrates the use of QP::QF::q_new_x().

Definition at line 1160 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

Description
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]eevent to create a reference to
[in,out]evtRefreference object (of the type evtT_*
Returns
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 1186 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

Description
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
Returns
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 1195 of file qp.hpp.

◆ newXfromISR_()

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

◆ gcFromISR()

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

◆ bzero_()

void QP::QF::bzero_ ( void *const start,
std::uint_fast16_t const len )
noexcept

Definition at line 81 of file qf_act.cpp.

Variable Documentation

◆ NO_MARGIN

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

Definition at line 1095 of file qp.hpp.

◆ priv_

QF::Attr QP::QF::priv_

Definition at line 78 of file qf_act.cpp.