QP/C++
Classes | Defines | Variables
qf.h File Reference

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

#include <new>
#include "qs_port.h"

Go to the source code of this file.

Classes

class  QActive
 Base class for derivation of application-level active object classes. More...
class  QTimeEvt
 Time Event class. More...
class  QSubscrList
 Subscriber List class. More...
class  QF
 QF services. More...

Defines

#define QF_ACTIVE_SUPER_   QHsm
 The macro defining the base class for QActive.
#define QF_ACTIVE_STATE_   QStateHandler
 The argument of the base class' constructor.
#define Q_NEW(evtT_, sig_)   ((evtT_ *)QF::new_(sizeof(evtT_), (sig_)))
 Allocate a dynamic event.
#define TICK(sender_)   tick(sender_)
 Invoke the system clock tick processing QF::tick(). 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.
#define PUBLISH(e_, sender_)   publish((e_), (sender_))
 Invoke the event publishing facility QF::publish(). 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.
#define POST(e_, sender_)   postFIFO((e_), (sender_))
 Invoke the direct event posting facility QActive::postFIFO(). This macro is the recommended way of posting events, because it provides the vital information for software tracing and avoids any overhead when the tracing is disabled.
#define QS_EQC_(ctr_)   QS::u8_(ctr_)
 Internal QS macro to output an unformatted event queue counter data element.

Variables

uint8_t const Q_ROM Q_ROM_VAR QF_log2Lkup [256]
 Lookup table for (log2(n) + 1), where n is the index into the table.
uint8_t const Q_ROM Q_ROM_VAR QF_pwr2Lkup [65]
 Lookup table for (1 << ((n-1) % 8)), where n is the index into the table.
uint8_t const Q_ROM Q_ROM_VAR QF_invPwr2Lkup [65]
 Lookup table for ~(1 << ((n-1) % 8)), where n is the index into the table.
uint8_t const Q_ROM Q_ROM_VAR QF_div8Lkup [65]
 Lookup table for (n-1)/8.

Detailed Description

QF/C++ platform-independent public interface.

This header file must be included directly or indirectly in all modules (*.cpp files) that use QF/C++.

Definition in file qf.h.


Define Documentation

#define POST (   e_,
  sender_ 
)    postFIFO((e_), (sender_))

Invoke the direct event posting facility QActive::postFIFO(). This macro is the recommended way of posting events, because it provides the vital information for software tracing and avoids any overhead when the tracing is disabled.

This macro takes the last argument sender_, which is a pointer to the sender object. This argument is actually only used when QS software tracing is disabled (macro #Q_SPY is defined). When QS software tracing is not enabled, the macro calls QF_publish() without the sender_ argument, so the overhead of passing this extra argument is entirely avoided.

Note:
the pointer to the sender object is not necessarily a poiner to an active object. In fact, if ao->POST() 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:
QActive::postFIFO()

Definition at line 1079 of file qf.h.

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

Invoke the event publishing facility QF::publish(). 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.

This macro takes the last argument sender_, which is a pointer to the sender object. This argument 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_ argument, so the overhead of passing this extra argument is entirely avoided.

Note:
the pointer to the sender object is not necessarily a poiner 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:
QF::publish()

Definition at line 1058 of file qf.h.

#define Q_NEW (   evtT_,
  sig_ 
)    ((evtT_ *)QF::new_(sizeof(evtT_), (sig_)))

Allocate a dynamic event.

This macro returns an event pointer cast to the type evtT_. The event is initialized with the signal sig. Internally, the macro calls the internal QF function QF::new_(), which always returns a valid event pointer.

Note:
The internal QF function QF::new_() raises an assertion when the allocation of the event turns out to be impossible due to event pool depletion, or incorrect (too big) size of the requested event.

The following example illustrates dynamic allocation of an event:

extern QActive *AO_Table;

QState Philosopher::hungry(Philosopher *me, QEvent const *e) {
    TableEvt *pe;
    switch (e->sig) {
        case Q_ENTRY_SIG: {
            pe = Q_NEW(TableEvt, HUNGRY_SIG);    // dynamically allocate event
            pe->philNum = me->num_;
            AO_Table->postFIFO(pe);               // post the event directly
            return Q_HANDLED();
        }
        . . .
    }
    return Q_SUPER(&QHsm::top);
}

Definition at line 895 of file qf.h.

#define QF_ACTIVE_SUPER_   QHsm

The macro defining the base class for QActive.

By default, the QActive class is derived from QHsm. However, if the macro QF_ACTIVE_SUPER_ is defined, QActive is derived from QF_ACTIVE_SUPER_.

Clients might choose, for example, to define QF_ACTIVE_SUPER_ as QFsm to avoid the 1-2KB overhead of the hierarchical event processor.

Clients might also choose to define QF_ACTIVE_SUPER_ as their own completely customized class that has nothing to do with QHsm or QFsm. The QF_ACTIVE_SUPER_ class must provide member functions init() and dispatch(), consistent with the signatures of QHsm and QFsm. But the implementatin of these functions is completely open.

Definition at line 93 of file qf.h.

#define QS_EQC_ (   ctr_)    QS::u8_(ctr_)

Internal QS macro to output an unformatted event queue counter data element.

Note:
the counter size depends on the macro QF_EQUEUE_CTR_SIZE.

Definition at line 1086 of file qf.h.

Referenced by QEQueue::get(), QActive::get_(), QEQueue::init(), QEQueue::postFIFO(), QActive::postFIFO(), QEQueue::postLIFO(), and QActive::postLIFO().

#define TICK (   sender_)    tick(sender_)

Invoke the system clock tick processing QF::tick(). 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.

This macro takes the argument sender_, which is a pointer to the sender object. This argument 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::tick() without any arguments, so the overhead of passing this extra argument is entirely avoided.

Note:
the pointer to the sender object is not necessarily a poiner to an active object. In fact, typically QF::TICK() will be called from an interrupt, in which case you would create a unique object just to unambiguously identify the ISR as the sender of the time events.
See also:
QF::tick()

Definition at line 1037 of file qf.h.


Variable Documentation

uint8_t const Q_ROM Q_ROM_VAR QF_div8Lkup[65]

Lookup table for (n-1)/8.

Note:
Index range n = 0..64. The first index (n == 0) should never be used.

Definition at line 63 of file qf_pwr2.cpp.

Referenced by QPSet64::hasElement(), QPSet64::insert(), QPSet64::remove(), QActive::subscribe(), QActive::unsubscribe(), and QActive::unsubscribeAll().

uint8_t const Q_ROM Q_ROM_VAR QF_invPwr2Lkup[65]

Lookup table for ~(1 << ((n-1) % 8)), where n is the index into the table.

Note:
Index range n = 0..64. The first index (n == 0) should never be used.

Definition at line 51 of file qf_pwr2.cpp.

Referenced by QF::publish(), QPSet8::remove(), QPSet64::remove(), QActive::unsubscribe(), and QActive::unsubscribeAll().

uint8_t const Q_ROM Q_ROM_VAR QF_log2Lkup[256]

Lookup table for (log2(n) + 1), where n is the index into the table.

This lookup delivers the 1-based number of the most significant 1-bit of a byte.

Note:
Index range n = 0..255. The first index (n == 0) should never be used.

Definition at line 39 of file qf_log2.cpp.

Referenced by QPSet8::findMax(), QPSet64::findMax(), and QF::publish().

uint8_t const Q_ROM Q_ROM_VAR QF_pwr2Lkup[65]

Lookup table for (1 << ((n-1) % 8)), where n is the index into the table.

Note:
Index range n = 0..64. The first index (n == 0) should never be used.

Definition at line 39 of file qf_pwr2.cpp.

Referenced by QPSet8::hasElement(), QPSet8::insert(), QActive::subscribe(), and QActive::unsubscribeAll().