Class CHeartbeat

class CHeartbeat : public CTimer;

Description

Heatbeat timer.

This class generates regular heartbeat events on a fixed fraction of a second. It is more accurate than a CPeriodic timer, because it provides a function to restore timer accuracy if it gets out of synchronisation with the system clock.

The protected CHeartbeat::RunL() function is called when the timer completes. The CHeartbeat::RunL() function in turn calls either the MBeating::Beat() or the MBeating::Synchronize() functions; MBeating is specified as a parameter to the CHeartbeat::Start(TTimerLockSpec,MBeating *) function used to start the heartbeat timer.

The relevant MBeating function may not be called immediately after the signal from the timer request has been generated, for the following reasons:

1. the CHeartbeat::RunL() of another active object may be running at the time of the signal

2. other active objects may have a higher priority than the CHeartbeat

If no heartbeat is missed, then the Beat() function is called.

If one or more heartbeats are missed then the Synchronize() function is called. It is important to bear in mind that the machine might be switched off after a few beats of the heart, and then Synchronize() will be called several days later. It is therefore essential that synchronisation is achieved as quickly as possible, rather than trying to catch up a tick at a time. In the context of an analogue clock, for instance, the clock should just redraw itself with the current time - rather than moving the hands round in steps until the time is correct.

CHeartbeat is an active object, derived from CActive (via CTimer). You should be familiar with CActive in order to understand CHeartbeat behaviour, but not necessarily with CTimer.

Derivation

• CBase - Base class for all classes to be instantiated on the heap.

• CActive - The core class of the active object abstraction.

• CTimer - Base class for a timer active object.

• CHeartbeat - Heatbeat timer.

Members

Defined in CHeartbeat:

• CHeartbeat(TInt)Protected constructor with a priority. Use this constructor to set the priority ...
• New(TInt)Allocates and constructs a CHeartbeat object - non-leaving.
• NewL(TInt)Allocates and constructs a CHeartbeat object - leaving.
• RunL()Handles an active object's request completion event.
• Start(TTimerLockSpec,MBeating *)Starts generating heartbeat events. The event results in calls to the Beat() and...
• ~CHeartbeat()Destructor.

Inherited from CActive:

• CActive(TInt)Constructs the active object with the specified priority.
• Cancel()Cancels the wait for completion of an outstanding request.
• Deque()Removes the active object from the active scheduler's list of active objects.
• EPriorityHighA priority higher than EPriorityUserInput.
• EPriorityIdleA low priority, useful for active objects representing background processing.
• EPriorityLowA priority higher than EPriorityIdle but lower than EPriorityStandard.
• EPriorityStandardMost active objects will have this priority.
• EPriorityUserInputA priority higher than EPriorityStandard; useful for active objects handling use...
• Extension_(TUint,TAny *&,TAny *)Extension function
• IsActive()constDetermines whether the active object has a request outstanding.
• IsAdded()constDetermines whether the active object has been added to the active scheduler's li...
• Priority()constGets the priority of the active object.
• RunError(TInt)Handles a leave occurring in the request completion event handler CActive::RunL(...
• SetActive()Indicates that the active object has issued a request and that it is now outstan...
• SetPriority(TInt)Sets the priority of the active object.
• TPriorityDefines standard priorities for active objects.
• iStatusThe request status associated with an asynchronous request.

Inherited from CBase:

• Delete(CBase *)Deletes the specified object.
• operator new(TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TAny *)Initialises the object to binary zeroes.
• operator new(TUint,TLeave)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TLeave,TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TUint)Allocates the object from the heap and then initialises its contents to binary z...

Inherited from CTimer:

• After(TTimeIntervalMicroSeconds32)Requests an event after an interval.
• At(const TTime &)Requests an event at a given local time.
• AtUTC(const TTime &)Requests an event at a given UTC time.
• CTimer(TInt)Protected constructor with priority.
• ConstructL()Constructs a new asynchronous timer.
• DoCancel()Implements cancellation of an outstanding request.
• HighRes(TTimeIntervalMicroSeconds32)Requests an event after the specified interval to a resolution of 1ms. The "...
• Inactivity(TTimeIntervalSeconds)Requests an event if no activity occurs within the specified interval.
• Lock(TTimerLockSpec)Requests an event on a specified second fraction.

IMPORT_C static CHeartbeat* NewL(TInt aPriority);

Description

Allocates and constructs a CHeartbeat object - leaving.

Specify a high priority so the callback function is scheduled as soon as possible after the timer events complete.

Parameters

TInt aPriority The priority of the active object. If timing is critical, it should be higher than that of all other active objects owned by the scheduler.

Return value

CHeartbeat * Pointer to new CHeartbeat object. The object is initialised and added to the active scheduler.

IMPORT_C ~CHeartbeat();

Description

Destructor.

Frees resources prior to destruction.

protected: IMPORT_C CHeartbeat(TInt aPriority);

Description

Protected constructor with a priority. Use this constructor to set the priority of the active object.

Classes derived from CHeartbeat must define and provide a constructor through which the priority of the active object can be passed. Such a constructor can call CHeartbeat's constructor in its constructor initialisation list.

Parameters

TInt aPriority The priority of the timer.

IMPORT_C static CHeartbeat* New(TInt aPriority);

Description

Allocates and constructs a CHeartbeat object - non-leaving.

Specify a high priority so the callback function is scheduled as soon as possible after the timer events complete.

Parameters

TInt aPriority The priority of the active object. If timing is critical, it should be higher than that of all other active objects owned by the scheduler.

Return value

CHeartbeat * Pointer to new CHeartbeat object. The object is initialised and added to the active scheduler. This value is NULL if insufficient memory was available.

IMPORT_C void Start(TTimerLockSpec aLock, MBeating *aBeating);

Description

Starts generating heartbeat events. The event results in calls to the Beat() and Synchronize() functions specified by aBeating.

The first event is generated on the first fraction of a second corresponding to aLock that occurs after CHeartbeat::Start(TTimerLockSpec,MBeating *) has returned; subsequent events are generated regularly thereafter at one second intervals on the second fraction specified by aLock.

The aBeating mixin must be written by the user. Most of the time, its Beat() function is called which trivially updates the tick count. Occasionally, synchronisation is lost, and the Synchronize() function is called instead: this must find out from the system time how many ticks should have been counted, and update things accordingly.

Once started, heartbeat events are generated until the CHeartbeat object is destroyed.

Parameters

TTimerLockSpec aLock The fraction of a second at which the timer completes. MBeating *aBeating Provides the Beat() and Synchronize() functions.

protected: IMPORT_C virtual void RunL();

Description

Handles an active object's request completion event.

A derived class must provide an implementation to handle the completed request. If appropriate, it may issue another request.

The function is called by the active scheduler when a request completion event occurs, i.e. after the active scheduler's WaitForAnyRequest() function completes.

Before calling this active object's CHeartbeat::RunL() function, the active scheduler has:

1. decided that this is the highest priority active object with a completed request

2. marked this active object's request as complete (i.e. the request is no longer outstanding)

CHeartbeat::RunL() runs under a trap harness in the active scheduler. If it leaves, then the active scheduler calls CActive::RunError(TInt) to handle the leave.

Note that once the active scheduler's CHeartbeat::Start(TTimerLockSpec,MBeating *) function has been called, all user code is run under one of the program's active object's CHeartbeat::RunL() or CActive::RunError(TInt) functions.

See also:

• CActiveScheduler::Start()Starts a new wait loop under the control of the current active scheduler.
• CActiveScheduler::Error(TInt)constHandles the result of a leave occurring in an active object’s RunL() function.
• CActiveScheduler::WaitForAnyRequest()Wait for an asynchronous request to complete.