QP/C++  6.9.3
Real-Time Embedded Framework
QTimeEvt Class Reference

#include <qf.hpp>

Inheritance diagram for QTimeEvt:
Inheritance graph
Collaboration diagram for QTimeEvt:
Collaboration graph

Public Member Functions

 QTimeEvt (QActive *const act, enum_t const sgnl, std::uint_fast8_t const tickRate=0U) noexcept
 The Time Event constructor. More...
 
void armX (QTimeEvtCtr const nTicks, QTimeEvtCtr const interval=0U) noexcept
 Arm a time event (one shot or periodic) for event posting. More...
 
bool disarm (void) noexcept
 Disarm a time event. More...
 
bool rearm (QTimeEvtCtr const nTicks) noexcept
 Rearm a time event. More...
 
bool wasDisarmed (void) noexcept
 Check the "was disarmed" status of a time event. More...
 
QTimeEvtCtr currCtr (void) const noexcept
 Get the current value of the down-counter of a time event. More...
 

Private Member Functions

 QTimeEvt (void) noexcept
 private default constructor only for friends More...
 
 QTimeEvt (QTimeEvt const &)=delete
 private copy constructor to disallow copying of QTimeEvts More...
 
QTimeEvtoperator= (QTimeEvt const &)=delete
 private assignment operator to disallow assigning of QTimeEvts More...
 
QActivetoActive (void) noexcept
 encapsulate the cast the m_act attribute to QActive* More...
 
QTimeEvttoTimeEvt (void) noexcept
 encapsulate the cast the m_act attribute to QTimeEvt* More...
 

Private Attributes

QTimeEvt *volatile m_next
 link to the next time event in the list More...
 
void *volatile m_act
 
QTimeEvtCtr volatile m_ctr
 
QTimeEvtCtr m_interval
 

Friends

class QF
 
class QS
 

Additional Inherited Members

- Data Fields inherited from QEvt
QSignal sig
 signal of the event instance More...
 
std::uint8_t poolId_
 pool ID (0 for static event) More...
 
std::uint8_t volatile refCtr_
 reference counter More...
 

Detailed Description

Time Event class

Description
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 QP::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 QP::QF::tickX_() 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 macro TICK_X(), which must be called periodically, from the clock tick ISR or from the special QP::QTicker active object.
Even though QP::QTimeEvt is a subclass of QP::QEvt, QP::QTimeEvt instances can NOT be allocated dynamically from event pools. In other words, it is illegal to allocate QP::QTimeEvt instances with the Q_NEW() or Q_NEW_X() macros.

Definition at line 404 of file qf.hpp.

Constructor & Destructor Documentation

◆ QTimeEvt() [1/3]

QTimeEvt ( QActive *const  act,
enum_t const  sgnl,
std::uint_fast8_t const  tickRate = 0U 
)
noexcept

The Time Event constructor.

Description
When creating a time event, you must commit it to a specific active object act, tick rate tickRate and event signal sgnl. You cannot change these attributes later.
Parameters
[in]actpointer to the active object associated with this time event. The time event will post itself to this AO.
[in]sgnlsignal to associate with this time event.
[in]tickRatesystem tick rate to associate with this time event.
Precondition
The signal must be valid and the tick rate in range

Definition at line 231 of file qf_time.cpp.

◆ QTimeEvt() [2/3]

QTimeEvt ( void  )
privatenoexcept

private default constructor only for friends

Note
private default ctor for internal use only

Definition at line 268 of file qf_time.cpp.

◆ QTimeEvt() [3/3]

QTimeEvt ( QTimeEvt const &  )
privatedelete

private copy constructor to disallow copying of QTimeEvts

Member Function Documentation

◆ armX()

void armX ( QTimeEvtCtr const  nTicks,
QTimeEvtCtr const  interval = 0U 
)
noexcept

Arm a time event (one shot or periodic) for event posting.

Description
Arms a time event to fire in a specified number of clock ticks and with a specified interval. If the interval is zero, the time event is armed for one shot ('one-shot' time event). The time event gets directly posted (using the FIFO policy) into the event queue of the host active object.
Parameters
[in]nTicksnumber of clock ticks (at the associated rate) to rearm the time event with.
[in]intervalinterval (in clock ticks) for periodic time event.
Note
After posting, a one-shot time event gets automatically disarmed while a periodic time event (interval != 0) is automatically re-armed.
A time event can be disarmed at any time by calling QP::QTimeEvt::disarm(). Also, a time event can be re-armed to fire in a different number of clock ticks by calling the QP::QTimeEvt::rearm() function.
Usage
The following example shows how to arm a one-shot time event from a state machine of an active object:
namespace DPP {
. . .
Q_STATE_DEF(Philo, eating) {
QP::QState status;
switch (e->sig) {
case Q_ENTRY_SIG: {
m_timeEvt.armX(eat_time());
status = Q_RET_HANDLED;
break;
}
case Q_EXIT_SIG: {
TableEvt *pe = Q_NEW(TableEvt, DONE_SIG);
pe->philoNum = PHILO_ID(this);
QP::QF::PUBLISH(pe, me);
m_timeEvt.disarm();
status = Q_RET_HANDLED);
break;
}
case TIMEOUT_SIG: {
status = tran(&thinking);
break;
}
case EAT_SIG: // intentionally fall through
case DONE_SIG: {
// EAT or DONE must be for other Philos than this one
Q_ASSERT(Q_EVT_CAST(TableEvt)->philoNum != PHILO_ID(this));
status = Q_RET_HANDLED;
break;
}
default: {
status = super(&top);
break;
}
}
return status;
}
} // namespace DPP
std::uint_fast8_t QState
Type returned from state-handler functions.
Definition: qep.hpp:223
#define Q_ASSERT(test_)
Definition: qassert.h:136
#define Q_EVT_CAST(class_)
Definition: qep.hpp:108
#define Q_NEW(evtT_, sig_)
Definition: qf.hpp:715
#define PUBLISH(e_, sender_)
Definition: qf.hpp:839
Precondition
the host AO must be valid, time evnet must be disarmed, number of clock ticks cannot be zero, and the signal must be valid.

Definition at line 324 of file qf_time.cpp.

◆ disarm()

bool disarm ( void  )
noexcept

Disarm a time event.

Description
Disarm the time event so it can be safely reused.
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.
Note
there is no harm in disarming an already disarmed time event

Definition at line 400 of file qf_time.cpp.

◆ rearm()

bool rearm ( QTimeEvtCtr const  nTicks)
noexcept

Rearm a time event.

Description
Rearms a time event with a new number of clock ticks. This function can be used to adjust the current period of a periodic time event or to prevent a one-shot time event from expiring (e.g., a watchdog time event). Rearming a periodic timer leaves the interval unchanged and is a convenient method to adjust the phasing of a periodic time event.
Parameters
[in]nTicksnumber of clock ticks (at the associated rate) to rearm the time event with.
Returns
'true' if the time event was running as it was re-armed. The 'false' return 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.
Precondition
AO must be valid, tick rate must be in range, nTicks must not be zero, and the signal of this time event must be valid

Definition at line 460 of file qf_time.cpp.

◆ wasDisarmed()

bool wasDisarmed ( void  )
noexcept

Check the "was disarmed" status of a time event.

Description
Useful for checking whether a one-shot time event was disarmed in the QTimeEvt_disarm() operation.
Returns
'true' if the time event was truly disarmed in the last QTimeEvt::disarm() operation. The 'false' return means that the time event was not truly disarmed, because it was not running at that time. 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 event queue.
Note
This function has a side effect of setting the "was disarmed" status, which means that the second and subsequent times this function is called the function will return 'true'.

Definition at line 541 of file qf_time.cpp.

◆ currCtr()

QTimeEvtCtr currCtr ( void  ) const
noexcept

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

Description
Useful for checking how many clock ticks (at the tick rate associated with the time event) remain until the time event expires.
Returns
For an armed time event, 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 560 of file qf_time.cpp.

◆ operator=()

QTimeEvt& operator= ( QTimeEvt const &  )
privatedelete

private assignment operator to disallow assigning of QTimeEvts

◆ toActive()

QActive* toActive ( void  )
inlineprivatenoexcept

encapsulate the cast the m_act attribute to QActive*

Definition at line 464 of file qf.hpp.

◆ toTimeEvt()

QTimeEvt* toTimeEvt ( void  )
inlineprivatenoexcept

encapsulate the cast the m_act attribute to QTimeEvt*

Definition at line 469 of file qf.hpp.

Friends And Related Function Documentation

◆ QF

friend class QF
friend

Definition at line 473 of file qf.hpp.

◆ QS

friend class QS
friend

Definition at line 474 of file qf.hpp.

Field Documentation

◆ m_next

QTimeEvt* volatile m_next
private

link to the next time event in the list

Definition at line 408 of file qf.hpp.

◆ m_act

void* volatile m_act
private

the active object that receives the time events

Description
The m_act pointer is reused inside the QP implementation to hold the head of the list of newly armed time events.

Definition at line 414 of file qf.hpp.

◆ m_ctr

QTimeEvtCtr volatile m_ctr
private

the internal down-counter of the time event.

Description
The down-counter is decremented by 1 in every TICK_X() invocation. The time event fires (gets posted or published) when the down-counter reaches zero.

Definition at line 421 of file qf.hpp.

◆ m_interval

QTimeEvtCtr m_interval
private

the interval for the periodic time event (zero for the one-shot time event).

Description
The value of the interval is re-loaded to the internal down-counter when the time event expires, so that the time event keeps timing out periodically.

Definition at line 429 of file qf.hpp.


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