Time Event class. More...

#include <qf.h>

Inherits QEvt.

Public Member Functions
	QTimeEvt (enum_t const s)
	The Time Event constructor.
void	postIn (QActive *const act, QTimeEvtCtr const nTicks)
	Arm a one-shot time event for direct event posting.
void	postEvery (QActive *const act, QTimeEvtCtr const nTicks)
	Arm a periodic time event for direct event posting.
bool	disarm (void)
	Disarm a time event.
bool	rearm (QTimeEvtCtr const nTicks)
	Rearm a time event.
QTimeEvtCtr	ctr (void) const
	Get the current value of the down-counter of a time event.
Friends
class	QF

Detailed Description

Time Event class.

Time events are special QF events equipped with the notion of time passage. The basic usage model of the time events is as follows. An active object allocates one or more QTimeEvt objects (provides the storage for them). When the active object needs to arrange for a timeout, it arms one of its time events to fire either just once (one-shot) or periodically. Each time event times out independently from the others, so a QF application can make multiple parallel timeout requests (from the same or different active objects). When QF detects that the appropriate moment has arrived, it inserts the time event directly into the recipient's event queue. The recipient then processes the time event just like any other event.

Time events, as any other QF events derive from the ::QEvt base class. Typically, you will use a time event as-is, but you can also further derive more specialized time events from it by adding some more data members and/or specialized functions that operate on the specialized time events.

Internally, the armed time events are organized into a bi-directional linked list. This linked list is scanned in every invocation of the QF::tick() function. Only armed (timing out) time events are in the list, so only armed time events consume CPU cycles.

Note:: QF manages the time events in the function QF::tick(), which must be called periodically, preferably from the clock tick ISR.; In this version of QF QTimeEvt objects should be allocated statically rather than dynamically from event pools. Currently, QF will not correctly recycle the dynamically allocated Time Events.

Definition at line 435 of file qf.h.

Constructor & Destructor Documentation

QP_BEGIN_ QTimeEvt::QTimeEvt ( enum_t const s )

The Time Event constructor.

The most important initialization performed in the constructor is assigning a signal to the Time Event. You can reuse the Time Event any number of times, but you cannot change the signal. This is because pointers to Time Events might still be held in event queues and changing signal could to hard-to-detect errors.

The following example shows the use of QTimeEvt::QTimeEvt() constructor in the constructor initializer list of the Philosopher active object constructor that owns the time event

class Philosopher : public QActive {
    . . .
public:
    Philosopher::Philosopher()                   // public default constructor
    : QActive((QStateHandler)&Philosopher::initial),
      m_timeEvt(TIMEOUT_SIG)
    {}
    . . .
};

Definition at line 47 of file qte_ctor.cpp.

References Q_REQUIRE, Q_USER_SIG, QSignal, and u8_0.

Member Function Documentation

QP_BEGIN_ QTimeEvtCtr QTimeEvt::ctr ( void ) const

Get the current value of the down-counter of a time event.

If the time event is armed, the function returns the current value of the down-counter of the given time event. If the time event is not armed, the function returns 0.

/note The function is thread-safe.

Definition at line 44 of file qte_ctr.cpp.

References QS_BEGIN_NOCRIT_, QS_END_NOCRIT_, QS_OBJ_, QS_QF_TIMEEVT_CTR, QS_TIME_, and QS::teObj_.

QP_BEGIN_ bool QTimeEvt::disarm ( void )

Disarm a time event.

The time event gets disarmed and can be reused. The function returns true if the time event was truly disarmed, that is, it was running. The return of false means that the time event was not truly disarmed because it was not running. The 'false' return is only possible for one-shot time events that have been automatically disarmed upon expiration. In this case the 'false' return means that the time event has already been posted or published and should be expected in the active object's state machine.

Definition at line 45 of file qte_darm.cpp.

References QS_BEGIN_NOCRIT_, QS_END_NOCRIT_, QS_OBJ_, QS_QF_TIMEEVT_DISARM, QS_QF_TIMEEVT_DISARM_ATTEMPT, QS_TIME_, and QS::teObj_.

void QTimeEvt::postEvery	(	QActive *const	act,
		QTimeEvtCtr const	nTicks
	)		`[inline]`

Arm a periodic time event for direct event posting.

Arms a time event to fire every nTicks clock ticks (periodic time event). The time event gets directly posted (using the FIFO policy) into the event queue of the active object act.

After posting, the time event gets automatically re-armed to fire again in the specified nTicks clock ticks.

A periodic time event can be disarmed only by calling the QTimeEvt::disarm() function. After disarming, the time event can be reused for a one-shot or periodic timeout requests.

Note:: An attempt to reuse (arm again) a running periodic time event raises an assertion.

Also, a periodic time event can be re-armed to shorten or extend the current period by calling the QTimeEvt_rearm() function. After adjusting the current period, the periodic time event goes back timing out at the original rate.

Definition at line 513 of file qf.h.

void QTimeEvt::postIn	(	QActive *const	act,
		QTimeEvtCtr const	nTicks
	)		`[inline]`

Arm a one-shot time event for direct event posting.

Arms a time event to fire in nTicks clock ticks (one-shot time event). The time event gets directly posted (using the FIFO policy) into the event queue of the active object act.

After posting, the time event gets automatically disarmed and can be reused for a one-shot or periodic timeout requests.

A one-shot time event can be disarmed at any time by calling the QTimeEvt::disarm() function. Also, a one-shot time event can be re-armed to fire in a different number of clock ticks by calling the QTimeEvt::rearm() function.

The following example shows how to arm a one-shot time event from a state machine of an active object:

QState Philosopher::eating(Philosopher *me, QEvent const *e) {
    TableEvt *pe;
    switch (e->sig) {
        case Q_ENTRY_SIG: {
            me->timeEvt_.postIn(me, EAT_TIME);      // arm one-shot time event
            return Q_HANDLED();
        }
        case TIMEOUT_SIG: {
            return Q_TRAN(&Philosopher::thinking);
        }
        case Q_EXIT_SIG: {
            busyDelay();
            pe = Q_NEW(TableEvt, DONE_SIG);
            pe->philNum = me->m_num;
            QF::publish(pe);
            return Q_HANDLED();
        }
    }
    return Q_SUPER(&QHsm::top);
}

Definition at line 488 of file qf.h.

QP_BEGIN_ bool QTimeEvt::rearm ( QTimeEvtCtr const nTicks )

Rearm a time event.

The time event gets rearmed with a new number of clock ticks nTicks. This facility can be used to prevent a one-shot time event from expiring (e.g., a watchdog time event), or to adjusts the current period of a periodic time event. Rearming a periodic timer leaves the interval unchanged and is a convenient method to adjust the phasing of the periodic time event.

The function returns true if the time event was running as it was re-armed. The return of false means that the time event was not truly rearmed because it was not running. The 'false' return is only possible for one-shot time events that have been automatically disarmed upon expiration. In this case the 'false' return means that the time event has already been posted or published and should be expected in the active object's state machine.

Definition at line 47 of file qte_rarm.cpp.

References Q_REQUIRE, Q_USER_SIG, QF_EVT_REF_CTR_INC_(), QF_timeEvtListHead_, QS_BEGIN_NOCRIT_, QS_END_NOCRIT_, QS_OBJ_, QS_QF_TIMEEVT_REARM, QS_TIME_, QS_U8_, QS::teObj_, u8_0, and u8_1.

The documentation for this class was generated from the following files:

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation