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.