CIdle Class Reference

An active object that performs low-priority processing when no higher-priority active objects are ready to run. More...

#include <e32base.h>

Inheritance diagram for CIdle:

Public Member Functions
IMPORT_C	~CIdle ()
	Frees resources prior to destruction.
IMPORT_C void	Start (TCallBack aCallBack)
	Starts the background task.
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 CIdle *	New (TInt aPriority)
	Allocates and initialises an Idle time active object and adds it to the active scheduler.
static IMPORT_C CIdle *	NewL (TInt aPriority)
	Allocates and initialises an Idle time active object, adds it to the active scheduler, but leaves on failure.
Static Public Member Functions inherited from CBase
static IMPORT_C void	Delete (CBase *aPtr)
	Deletes the specified object.

Protected Member Functions
IMPORT_C	CIdle (TInt aPriority)
	Protected constructor taking a priority value.
IMPORT_C void	RunL ()
	Handles an active object's request completion event.
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.

Protected Attributes
TCallBack	iCallBack
	The callback object that encapsulates the background task.

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

An active object that performs low-priority processing when no higher-priority active objects are ready to run.

An idle time active object together with its associated callback function may be used to implement potentially long running background tasks, such as spreadsheet recalculation and word processor repagination.

API status

Published to all clients. Released API.

Definition at line 1767 of file e32base.h.

Constructor & Destructor Documentation

~CIdle()

IMPORT_C CIdle::~CIdle

(

)

Frees resources prior to destruction.

Specifically, it cancels any outstanding request.

(generated from Symbian Developer Library)

CIdle()

IMPORT_C CIdle::CIdle ( TInt  aPriority )

protected

Protected constructor taking a priority value.

Sets this active object's priority value.

Parameters

aPriority

The active object priority value.

(generated from Symbian Developer Library)

Member Function Documentation

DoCancel()

IMPORT_C void CIdle::DoCancel ( )

protectedvirtual

Implements cancellation of an outstanding request.

This function is called as part of the active object's Cancel().

It must call the appropriate cancel function offered by the active object's asynchronous service provider. The asynchronous service provider's cancel is expected to act immediately.

DoCancel() must not wait for event completion; this is handled by Cancel().

See also

CActive::Cancel

Implements CActive.

New()

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

static

Allocates and initialises an Idle time active object and adds it to the active scheduler.

Parameters

aPriority

An integer specifying the priority of this active object. It must be lower than that of all other active objects on the active scheduler. The value CActive::TPriority::EPriorityIdle is recommended.

(generated from Symbian Developer Library)

NewL()

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

static

Allocates and initialises an Idle time active object, adds it to the active scheduler, but leaves on failure.

Parameters

aPriority

An integer specifying the priority of this active object. It must be lower than that of all other active objects on the active scheduler. The value CActive::TPriority::EPriorityIdle is recommended.

(generated from Symbian Developer Library)

RunL()

IMPORT_C void CIdle::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:

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)

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 CIdle::Start

(

TCallBack

aCallBack

)

Starts the background task.

The background task is encapsulated in the callback. The function represented by this callback is called every time this Idle time active object is scheduled to run.

The callback function should be structured to perform a background task in many increments, i.e. it should voluntarily relinquish control (i.e. return) after a suitable time interval to allow other, higher priority events to be handled.

If the callback function has further work to do, it should return a true value. This ensures that the active object is scheduled to run again later.

Once the callback function has finally completed its work, it should return a false value. The active object is then no longer scheduled to run.

Parameters

aCallBack

A callback object encapsulating a function which is called when no higher priority active object is ready to run.

(generated from Symbian Developer Library)

Member Data Documentation

iCallBack

TCallBack CIdle::iCallBack

protected

The callback object that encapsulates the background task.

See also

Start

Definition at line 1798 of file e32base.h.

---

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

• e32base.h
• e32base.h.dox