Periodic timer active object. More...

#include <e32base.h>

Inheritance diagram for CPeriodic:

Public Member Functions
IMPORT_C	~CPeriodic ()
	Destructor.

IMPORT_C void	Start (TTimeIntervalMicroSeconds32 aDelay, TTimeIntervalMicroSeconds32 anInterval, TCallBack aCallBack)
	Starts generating periodic events.

Public Member Functions inherited from CTimer
IMPORT_C	~CTimer ()
	Destructor.

IMPORT_C void	At (const TTime &aTime)
	Requests an event at a given local time.

IMPORT_C void	AtUTC (const TTime &aTimeInUTC)
	Requests an event at a given UTC time.

IMPORT_C void	After (TTimeIntervalMicroSeconds32 anInterval)
	Requests an event after an interval.

IMPORT_C void	Lock (TTimerLockSpec aLock)
	Requests an event on a specified second fraction.

IMPORT_C void	Inactivity (TTimeIntervalSeconds aSeconds)
	Requests an event if no activity occurs within the specified interval.

IMPORT_C void	HighRes (TTimeIntervalMicroSeconds32 aInterval)
	Requests an event after the specified interval to a resolution of 1ms.

Public Member Functions inherited from CActive
IMPORT_C	~CActive ()
	Frees resources prior to destruction.

IMPORT_C void	Cancel ()
	Cancels the wait for completion of an outstanding request.

IMPORT_C void	Deque ()
	Removes the active object from the active scheduler's list of active objects.

IMPORT_C void	SetPriority (TInt aPriority)
	Sets the priority of the active object.

TBool	IsActive () const
	Determines whether the active object has a request outstanding.

TBool	IsAdded () const
	Determines whether the active object has been added to the active scheduler's list of active objects.

TInt	Priority () const
	Gets the priority of the active object.

Public Member Functions inherited from CBase
	CBase ()
	Default constructor.

virtual IMPORT_C	~CBase ()
	Virtual destructor.

TAny *	operator new (TUint aSize, TAny *aBase) __NO_THROW
	Initialises the object to binary zeroes.

TAny *	operator new (TUint aSize) __NO_THROW
	Allocates the object from the heap and then initialises its contents to binary zeroes.

TAny *	operator new (TUint aSize, TLeave)
	Allocates the object from the heap and then initialises its contents to binary zeroes.

TAny *	operator new (TUint aSize, TUint aExtraSize) __NO_THROW
	Allocates the object from the heap and then initialises its contents to binary zeroes.

TAny *	operator new (TUint aSize, TLeave, TUint aExtraSize)
	Allocates the object from the heap and then initialises its contents to binary zeroes.

Static Public Member Functions
static IMPORT_C CPeriodic *	New (TInt aPriority)
	Allocates and constructs a CPeriodic object - non-leaving.

static IMPORT_C CPeriodic *	NewL (TInt aPriority)
	Allocates and constructs a CPeriodic object - leaving.

Static Public Member Functions inherited from CBase
static IMPORT_C void	Delete (CBase *aPtr)
	Deletes the specified object.

Protected Member Functions
IMPORT_C	CPeriodic (TInt aPriority)
	Protected constructor with priority.

IMPORT_C void	RunL ()
	Handles an active object's request completion event.

Protected Member Functions inherited from CTimer
IMPORT_C	CTimer (TInt aPriority)
	Protected constructor with priority.

IMPORT_C void	ConstructL ()
	Constructs a new asynchronous timer.

IMPORT_C void	DoCancel ()
	Implements cancellation of an outstanding request.

Protected Member Functions inherited from CActive
IMPORT_C	CActive (TInt aPriority)
	Constructs the active object with the specified priority.

IMPORT_C void	SetActive ()
	Indicates that the active object has issued a request and that it is now outstanding.

virtual IMPORT_C TInt	RunError (TInt aError)
	Handles a leave occurring in the request completion event handler RunL().

virtual IMPORT_C TInt	Extension_ (TUint aExtensionId, TAny &a0, TAny a1)
	Extension function.

Additional Inherited Members
Public Types inherited from CActive
enum	TPriority { EPriorityIdle =-100 , EPriorityLow =-20 , EPriorityStandard =0 , EPriorityUserInput =10 , EPriorityHigh =20 }
	Defines standard priorities for active objects. More...

Public Attributes inherited from CActive
TRequestStatus	iStatus
	The request status associated with an asynchronous request.

Detailed 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 Start().

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

the RunL() of another active object may be running at the time of the signal
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 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.

See also: CHeartbeat

API status: Published to all clients. Released API.

Definition at line 2056 of file e32base.h.

Constructor & Destructor Documentation

◆ ~CPeriodic()

IMPORT_C CPeriodic::~CPeriodic ( )

Destructor.

Frees resources prior to destruction.

(generated from Symbian Developer Library)

◆ CPeriodic()

IMPORT_C CPeriodic::CPeriodic ( TInt aPriority )

protected

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

aPriority The priority of the timer.

(generated from Symbian Developer Library)

Member Function Documentation

◆ New()

static IMPORT_C CPeriodic * CPeriodic::New ( TInt aPriority )

static

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

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.

(generated from Symbian Developer Library)

◆ NewL()

static IMPORT_C CPeriodic * CPeriodic::NewL ( TInt aPriority )

static

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

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.

Leave condition: KErrNoMemory There is insufficient memory to create the object.

(generated from Symbian Developer Library)

◆ RunL()

IMPORT_C void CPeriodic::RunL ( )

protectedvirtual

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 RunL() function, the active scheduler has:

decided that this is the highest priority active object with a completed request
marked this active object's request as complete (i.e. the request is no longer outstanding)

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

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

See also: CActiveScheduler::Start; CActiveScheduler::Error; CActiveScheduler::WaitForAnyRequest; TRAPD

Implements CActive.

◆ Start()

IMPORT_C void CPeriodic::Start	(	TTimeIntervalMicroSeconds32	aDelay,
		TTimeIntervalMicroSeconds32	anInterval,
		TCallBack	aCallBack
	)

Starts generating periodic events.

The event calls the protected 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:

The callback function will be run as soon as possible after the initial delay, and after each period.
The callback may be delayed because the 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 RunL()s of short duration.
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

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

Panic condition: E32USER-CBase 52, if anInterval is negative.

Panic condition: E32USER-CBase 53, if aDelay is negative.

(generated from Symbian Developer Library)

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

Public Member Functions

Static Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ ~CPeriodic()

◆ CPeriodic()

Member Function Documentation

◆ New()

◆ NewL()

◆ RunL()

◆ Start()