Class CPeriodic

class CPeriodic : public CTimer;

Description

Periodic timer active object.

This class generates regular timer events and handles them with a callback function. The callback is specified as a parameter to CPeriodic::Start(TTimeIntervalMicroSeconds32,TTimeIntervalMicroSeconds32,TCallBack).

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

1. the CPeriodic::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 CPeriodic

If timing accuracy is important to your application, you can minimise the first problem by ensuring all CPeriodic::RunL()s complete quickly, and can eliminate the second by giving the CPeriodic a higher priority than any other active object. Although it is generally recommended that timer-related active objects have a high priority, this will not address the problem of CPeriodic timers running behind, because active object scheduling is not pre-emptive.

After a timer signal generated by a CPeriodic, the next signal is requested just before running the callback, and this request can be delayed for the same reasons that running the callback can be delayed. Therefore, a large number N of periods may add up to somewhat more than N times the requested period time. If absolute precision is required in tracking time, do not rely on counting the number of times the callback is called: read the value of the system clock every time you need it.

For many applications, such precision is not required, for example, tick counting is sufficiently accurate for controlling time-outs in a communications program.

Note that you should be familiar with CActive in order to understand CPeriodic 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.

• CPeriodic - Periodic timer active object.

Members

Defined in CPeriodic:

• CPeriodic(TInt)Protected constructor with priority.
• New(TInt)Allocates and constructs a CPeriodic object - non-leaving.
• NewL(TInt)Allocates and constructs a CPeriodic object - leaving.
• RunL()Handles an active object's request completion event.
• Start(TTimeIntervalMicroSeconds32,TTimeIntervalMicroSeconds32,TCallBack)Starts generating periodic events.
• ~CPeriodic()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 CPeriodic* NewL(TInt aPriority);

Description

Allocates and constructs a CPeriodic 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

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

Leave codes

KErrNoMemory There is insufficient memory to create the object.

IMPORT_C ~CPeriodic();

Description

Destructor.

Frees resources prior to destruction.

protected: IMPORT_C CPeriodic(TInt aPriority);

Description

Protected constructor with priority.

Use this constructor to set the priority of the active object.

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

Parameters

TInt aPriority The priority of the timer.

IMPORT_C static CPeriodic* New(TInt aPriority);

Description

Allocates and constructs a CPeriodic 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

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

IMPORT_C void Start(TTimeIntervalMicroSeconds32 aDelay, TTimeIntervalMicroSeconds32 anInterval, TCallBack aCallBack);

Description

Starts generating periodic events.

The event calls the protected CPeriodic::RunL() function, which in turn calls the function specified by aCallBack. The first event is generated after aDelay microseconds; subsequent events are generated regularly thereafter at intervals of anInterval microseconds.

The TCallBack contains a function pointer and a TAny* pointer. The function will be repeatedly called with the pointer as a parameter.

Once started, periodic events are generated until the CPeriodic object is destroyed.

Notes:

1. The callback function will be run as soon as possible after the initial delay, and after each period.

2. The callback may be delayed because the CPeriodic::RunL() of another active object, with the deepest nesting-level active scheduler on the same thread, is running when the event occurs: this cannot be avoided, but can be minimised by making all CPeriodic::RunL()s of short duration.

3. The callback may be delayed because other, higher-priority, active objects are scheduled instead. This can be avoided by giving the CPeriodic a very high priority.

Parameters

TTimeIntervalMicroSeconds32 aDelay The delay from the CPeriodic::Start(TTimeIntervalMicroSeconds32,TTimeIntervalMicroSeconds32,TCallBack) function to the generation of the first event, in microseconds. TTimeIntervalMicroSeconds32 anInterval The interval between events generated after the initial delay, in microseconds. TCallBack aCallBack A callback specifying a function to be called when the CPeriodic is scheduled after a timer event.

Panic codes

E32USER-CBase 52, if anInterval is negative. E32USER-CBase 53, if aDelay is negative.

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 CPeriodic::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)

CPeriodic::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 CPeriodic::Start(TTimeIntervalMicroSeconds32,TTimeIntervalMicroSeconds32,TCallBack) function has been called, all user code is run under one of the program's active object's CPeriodic::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.