Using CIdle

This document describes how to use the CIdle class to implement long running background tasks.

An instance of the CIdle class, an idle time active object, can be used to perform 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.

A typical example is a background re-calculation in a spreadsheet. Assume that the spreadsheet is encapsulated by some class CSheet.

class CSheet
 {
 ...
 TInt LaunchReCalcL();
 TInt DoBackgroundRecalc();
 static TInt BackgroundRecalc(TAny *aSheet);
 ...
private:
 CIdle* iRecalc;
 ...
 };

Assume that a CSheet object has been created and that, as a result of user interaction or some other event, a background re-calculation is launched by a call to LaunchReCalc(). The implementation of this function would construct a CIdle object, specifying a suitably low priority. The value CActive::EPriorityIdle is recommended:

TInt CSheet::LaunchReCalcL()
 {
 ...
 if (!(iRecalc))
  {
  iRecalc = CIdle::NewL(CActive::EPriorityIdle);
  }
 ...
 iRecalc->Start(TCallBack(BackgroundRecalc,this)); 
 ...
 };

To start the background recalculation which is performed by the DoBackGroundRecalc() member function of CSheet, start by coding:

iRecalc->Start(TCallBack(BackgroundRecalc,this));

CIdle::Start() requires a TCallBack object to encapsulate the function to be called and a pointer to be passed as a parameter to that function. As the encapsulated function must either be static or a non-member function, the easiest way to handle this is to pass the static function BackgroundRecalc() and a pointer to the sheet object itself. BackgroundRecalc() then calls the non-static DoBackgroundRecalc():

TInt Sheet::BackgroundRecalc(TAny* aSheet)
 {
 return ((CSheet*)aSheet)->DoBackgroundRecalc();
 }

BackgroundRecalc() is called when there are no higher priority active objects with events to process. It does a small amount of recalculation before returning.

If the function has further work to do, it returns a true value to ensure that it is called again when there is no other higher priority event to handle. When the function finally completes its recalculation task, it returns a false value; the function is not called again.

Typically, an object such as CSheet or some other object accessible from CSheet, keeps track of the state of the re-calculation.

It is important for application responsiveness that each iteration of the idle time object take only a short time. All other events handled by the active scheduler, even high-priority ones, cannot be processed until the idle time object's callback function returns.

When the background recalculation is complete, the callback function is not called again. The idle time active object can be destroyed or left until needed again.

If Cancel() is called, the callback function is not called again. An application would need to implement appropriate cleanup.