Class CIdle

class CIdle : public CActive;

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.

Derivation

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

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

• CIdle - ...

Members

Defined in CIdle:

• CIdle(TInt)Protected constructor taking a priority value.
• DoCancel()Implements the cancellation of an outstanding request.
• New(TInt)Allocates and initialises an Idle time active object and adds it to the active s...
• NewL(TInt)Allocates and initialises an Idle time active object, adds it to the active sche...
• RunL()Handles this idle active object's request completion event.
• Start(TCallBack)Starts the background task.
• iCallBackThe callback object that encapsulates the background task.
• ~CIdle()Frees resources prior to destruction.

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...

IMPORT_C static CIdle* NewL(TInt aPriority);

Description

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

Parameters

TInt 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.

Return value

CIdle * Pointer to the new Idle time active object.

IMPORT_C ~CIdle();

Description

Frees resources prior to destruction.

Specifically, it cancels any outstanding request.

protected: IMPORT_C CIdle(TInt aPriority);

Description

Protected constructor taking a priority value.

Sets this active object's priority value.

Parameters

TInt aPriority The active object priority value.

IMPORT_C static CIdle* New(TInt aPriority);

Description

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

Parameters

TInt 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.

Return value

CIdle * Pointer to the new Idle time active object, or NULL if the object could not be created.

IMPORT_C void Start(TCallBack aCallBack);

Description

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

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

protected: IMPORT_C virtual void RunL();

Description

Handles this idle active object's request completion event.

It is called when nothing of a higher priority can be scheduled.

See also:

• CActive::RunL()Handles an active object's request completion event.

protected: IMPORT_C virtual void DoCancel();

Description

Implements the cancellation of an outstanding request.

This function is called by the active object's CActive::Cancel() function.

See also:

• CActive::DoCancel()Implements cancellation of an outstanding request.

protected: TCallBack iCallBack;

Description

The callback object that encapsulates the background task.

See also:

• CIdle::Start(TCallBack)Starts the background task.