QP/C++ 6.9.1
qf.hpp File Reference

QF/C++ platform-independent public interface. More...

#include "qpset.hpp"
Include dependency graph for qf.hpp:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

class  QActive
 QActive active object (based on QP::QHsm implementation) More...
 
class  QMActive
 QMActive active object (based on QP::QMsm implementation) More...
 
class  QTimeEvt
 Time Event class. More...
 
class  QF
 QF services. More...
 
class  QTicker
 Ticker Active Object class. More...
 

Namespaces

 QP
 namespace associated with the QP/C++ framework
 

Macros

#define QF_EVENT_SIZ_SIZE   2U
 Default value of the macro configurable value in qf_port.hpp. More...
 
#define QF_MAX_EPOOL   3U
 Default value of the macro configurable value in qf_port.hpp. More...
 
#define QF_MAX_TICK_RATE   1U
 Default value of the macro configurable value in qf_port.hpp Valid values: [0U..15U]; default 1U. More...
 
#define QF_TIMEEVT_CTR_SIZE   2U
 macro to override the default QTimeEvtCtr size. Valid values 1U, 2U, or 4U; default 2U More...
 
#define QF_CRIT_EXIT_NOP()   (static_cast<void>(0))
 No-operation for exiting a critical section. More...
 
#define Q_NEW(evtT_, sig_)
 Allocate a dynamic event. More...
 
#define Q_NEW_X(e_, evtT_, margin_, sig_)
 Allocate a dynamic event (non-asserting version). More...
 
#define Q_NEW_REF(evtRef_, evtT_)    ((evtRef_) = static_cast<evtT_ const *>(QP::QF::newRef_(e, (evtRef_))))
 Create a new reference of the current event e *‍/. More...
 
#define Q_DELETE_REF(evtRef_)
 Delete the event reference *‍/. More...
 
#define TICK_X(tickRate_, sender_)   tickX_((tickRate_), (sender_))
 Invoke the system clock tick processing QP::QF::tickX_(). More...
 
#define PUBLISH(e_, sender_)   publish_((e_), (sender_))
 Invoke the event publishing facility QP::QF::publish_(). This macro. More...
 
#define POST(e_, sender_)   post_((e_), QP::QF_NO_MARGIN, (sender_))
 Invoke the direct event posting facility QP::QActive::post_(). More...
 
#define POST_X(e_, margin_, sender_)    post_((e_), (margin_), (sender_))
 Invoke the direct event posting facility QP::QActive::post_() without delivery guarantee. More...
 
#define TICK(sender_)   TICK_X(0U, (sender_))
 Invoke the system clock tick processing for rate 0. More...
 

Typedefs

using QEvtSize = std::uint16_t
 The data type to store the block-size defined based on the macro QF_EVENT_SIZ_SIZE. More...
 
using QTimeEvtCtr = std::uint16_t
 type of the Time Event counter, which determines the dynamic range of the time delays measured in clock ticks. More...
 
using QSubscrList = QPSet
 Subscriber List. More...
 

Variables

std::uint_fast16_t const QF_NO_MARGIN = 0xFFFFU
 special value of margin that causes asserting failure in case event allocation or event posting fails More...
 

Detailed Description

QF/C++ platform-independent public interface.

Definition in file qf.hpp.

Macro Definition Documentation

◆ QF_EVENT_SIZ_SIZE

#define QF_EVENT_SIZ_SIZE   2U

Default value of the macro configurable value in qf_port.hpp.

Definition at line 56 of file qf.hpp.

◆ QF_MAX_EPOOL

#define QF_MAX_EPOOL   3U

Default value of the macro configurable value in qf_port.hpp.

Definition at line 61 of file qf.hpp.

◆ QF_MAX_TICK_RATE

#define QF_MAX_TICK_RATE   1U

Default value of the macro configurable value in qf_port.hpp Valid values: [0U..15U]; default 1U.

Definition at line 67 of file qf.hpp.

◆ QF_TIMEEVT_CTR_SIZE

#define QF_TIMEEVT_CTR_SIZE   2U

macro to override the default QTimeEvtCtr size. Valid values 1U, 2U, or 4U; default 2U

Definition at line 75 of file qf.hpp.

◆ QF_CRIT_EXIT_NOP

#define QF_CRIT_EXIT_NOP ( )    (static_cast<void>(0))

No-operation for exiting a critical section.

Description
In some QF ports the critical section exit takes effect only on the next machine instruction. If this next instruction is another entry to a critical section, the critical section won't be really exited, but rather the two adjecent critical sections would be merged. The QF_CRIT_EXIT_NOP() macro contains minimal code required to prevent such merging of critical sections in such merging of critical sections in QF ports, in which it can occur.

Definition at line 668 of file qf.hpp.

◆ Q_NEW

#define Q_NEW (   evtT_,
  sig_ 
)
Value:
(static_cast<evtT_ *>( \
QP::QF::newX_(sizeof(evtT_), QP::QF_NO_MARGIN, (sig_))))

Allocate a dynamic event.

Description
The macro calls the internal QF function QP::QF::newX_() with margin == QP::QF_NO_MARGIN, which causes an assertion when the event cannot be successfully allocated.
Parameters
[in]evtT_event type (class name) of the event to allocate
[in]sig_signal to assign to the newly allocated event
Returns
a valid event pointer cast to the type evtT_.
Note
If Q_EVT_CTOR is defined, the Q_NEW() macro becomes variadic and takes all the arguments needed by the constructor of the event class being allocated. The constructor is then called by means of the placement-new operator.
Usage
The following example illustrates dynamic allocation of an event:
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;
}

Definition at line 709 of file qf.hpp.

◆ Q_NEW_X

#define Q_NEW_X (   e_,
  evtT_,
  margin_,
  sig_ 
)
Value:
((e_) = static_cast<evtT_ *>(QP::QF::newX_( \
sizeof(evtT_), (margin_), (sig_))))

Allocate a dynamic event (non-asserting version).

Description
This macro allocates a new event and sets the pointer e_, while leaving at least margin_ of events still available in the pool
Parameters
[out]e_pointer to the newly allocated event
[in]evtT_event type (class name) of the event to allocate
[in]margin_number of events that must remain available in the given pool after this allocation. The special value QP::QF_NO_MARGIN causes asserting failure in case event allocation fails.
[in]sig_signal to assign to the newly allocated event
Returns
an event pointer cast to the type evtT_ or NULL if the event cannot be allocated with the specified margin.
Note
If Q_EVT_CTOR is defined, the Q_NEW_X() macro becomes variadic and takes all the arguments needed by the constructor of the event class being allocated. The constructor is then called by means of the placement-new operator.
Usage
The following example illustrates dynamic allocation of an event:
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 *te;
Q_NEW_X(te, TableEvt, 1U, HUNGRY_SIG, PHILO_ID(me));
if (te != nullptr) {
AO_Table->POST_X(te, 1U, me);
}
status_ = Q_HANDLED();
break;
}
. . .
default: {
status = Q_SUPER(&QHsm::top);
break;
}
}
return status;
}

Definition at line 737 of file qf.hpp.

◆ Q_NEW_REF

#define Q_NEW_REF (   evtRef_,
  evtT_ 
)     ((evtRef_) = static_cast<evtT_ const *>(QP::QF::newRef_(e, (evtRef_))))

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 macro 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 macro Q_DELETE_REF().
Parameters
[in,out]evtRef_event reference to create
[in]evtT_event type (class name) of the event refrence
Usage
The example defer in the directory examples/win32/defer illustrates the use of Q_NEW_REF()
See also
Q_DELETE_REF()

Definition at line 761 of file qf.hpp.

◆ Q_DELETE_REF

#define Q_DELETE_REF (   evtRef_)
Value:
do { \
QP::QF::deleteRef_((evtRef_)); \
(evtRef_) = 0U; \
} while (false)

Delete the event reference *‍/.

Description
Every event reference created with the macro Q_NEW_REF() needs to be eventually deleted by means of the macro Q_DELETE_REF() to avoid leaking the event.
Parameters
[in,out]evtRef_event reference to delete
Usage
The example defer in the directory examples/win32/defer illustrates the use of Q_DELETE_REF()
See also
Q_NEW_REF()

Definition at line 778 of file qf.hpp.

◆ TICK_X

#define TICK_X (   tickRate_,
  sender_ 
)    tickX_((tickRate_), (sender_))

Invoke the system clock tick processing QP::QF::tickX_().

Description
This macro is the recommended way of invoking clock tick processing, because it provides the vital information for software tracing and avoids any overhead when the tracing is disabled.
Parameters
[in]tickRate_clock tick rate to be serviced through this call
[in]sender_pointer to the sender object. This parameter is actually only used when QS software tracing is enabled (macro Q_SPY is defined)
Note
When QS software tracing is disabled, the macro calls QF_tickX_() without the sender parameter, so the overhead of passing this extra parameter is entirely avoided.
The pointer to the sender object is not necessarily a pointer to an active object. In fact, when TICK_X() is called from an interrupt, you would create a unique object just to unambiguously identify the ISR as the sender of the time events.
See also
QP::QF::tickX_()

Definition at line 810 of file qf.hpp.

◆ PUBLISH

#define PUBLISH (   e_,
  sender_ 
)    publish_((e_), (sender_))

Invoke the event publishing facility QP::QF::publish_(). This macro.

Description
This macro is the recommended way of publishing events, because it provides the vital information for software tracing and avoids any overhead when the tracing is disabled.
Parameters
[in]e_pointer to the posted event
[in]sender_pointer to the sender object. This parameter is actually only used when QS software tracing is enabled (macro Q_SPY is defined). When QS software tracing is disabled, the macro calls QF_publish_() without the sender_ parameter, so the overhead of passing this extra parameter is entirely avoided.
Note
The pointer to the sender object is not necessarily a pointer to an active object. In fact, if QF_PUBLISH() is called from an interrupt or other context, you can create a unique object just to unambiguously identify the publisher of the event.
See also
QP::QF::publish_()

Definition at line 833 of file qf.hpp.

◆ POST

#define POST (   e_,
  sender_ 
)    post_((e_), QP::QF_NO_MARGIN, (sender_))

Invoke the direct event posting facility QP::QActive::post_().

Description
This macro asserts if the queue overflows and cannot accept the event.
Parameters
[in]e_pointer to the event to post
[in]sender_pointer to the sender object.
Note
The sendedr_ parameter is actually only used when QS tracing is enabled (macro Q_SPY is defined). When QS software tracing is disenabled, the POST() macro does not pass the sender_ parameter, so the overhead of passing this extra parameter is entirely avoided.
the pointer to the sender object is not necessarily a pointer to an active object. In fact, if POST() is called from an interrupt or other context, you can create a unique object just to unambiguously identify the sender of the event.
See also
QP::QActive::post_()

Definition at line 855 of file qf.hpp.

◆ POST_X

#define POST_X (   e_,
  margin_,
  sender_ 
)     post_((e_), (margin_), (sender_))

Invoke the direct event posting facility QP::QActive::post_() without delivery guarantee.

Description
This macro does not assert if the queue overflows and cannot accept the event with the specified margin of free slots remaining.
Parameters
[in]e_pointer to the event to post
[in]margin_the minimum free slots in the queue, which must still be available after posting the event. The special value QP::QF_NO_MARGIN causes asserting failure in case event posting fails.
[in]sender_pointer to the sender object.
Returns
'true' if the posting succeeded, and 'false' if the posting failed due to insufficient margin of free entries available in the queue.
Note
The sender_ parameter is actually only used when QS tracing is enabled (macro Q_SPY is defined). When QS software tracing is disabled, the POST_X() macro does not pass the sender_ parameter, so the overhead of passing this extra parameter is entirely avoided.
The pointer to the sender object is not necessarily a pointer to an active object. In fact, if POST_X() is called from an interrupt or other context, you can create a unique object just to unambiguously identify the sender of the event.
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 *te;
Q_NEW_X(te, TableEvt, 1U, HUNGRY_SIG, PHILO_ID(me));
if (te != nullptr) {
AO_Table->POST_X(te, 1U, me);
}
status_ = Q_HANDLED();
break;
}
. . .
default: {
status = Q_SUPER(&QHsm::top);
break;
}
}
return status;
}

Definition at line 889 of file qf.hpp.

◆ TICK

#define TICK (   sender_)    TICK_X(0U, (sender_))

Invoke the system clock tick processing for rate 0.

See also
TICK_X()

Definition at line 903 of file qf.hpp.

QP::QState
std::uint_fast8_t QState
Type returned from state-handler functions.
Definition: qep.hpp:223
QP::QEvt
QEvt base class.
Definition: qep.hpp:209
QP::QEvt::sig
QSignal sig
signal of the event instance
Definition: qep.hpp:210
Q_HANDLED
#define Q_HANDLED()
Macro to specify that the event was handled.
Definition: qep.hpp:623
QP::QF_NO_MARGIN
std::uint_fast16_t const QF_NO_MARGIN
special value of margin that causes asserting failure in case event allocation or event posting fails
Definition: qf.hpp:621
QP::QF::newX_
static QEvt * newX_(std::uint_fast16_t const evtSize, std::uint_fast16_t const margin, enum_t const sig) noexcept
Internal QF implementation of creating new dynamic event.
Definition: qf_dyn.cpp:140
QP::QF::deleteRef_
static void deleteRef_(QEvt const *const evtRef) noexcept
Internal QF implementation of deleting event reference.
Definition: qf_dyn.cpp:325
Q_NEW
#define Q_NEW(evtT_, sig_)
Allocate a dynamic event.
Definition: qf.hpp:709
Q_NEW_X
#define Q_NEW_X(e_, evtT_, margin_, sig_)
Allocate a dynamic event (non-asserting version).
Definition: qf.hpp:737
Q_SUPER
#define Q_SUPER(state_)
Definition: qpcpp.hpp:152