|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-162A4409-1ABB-51A1-B7F1-75A31A5DEA63" xml:lang="en"><title>Using |
|
13 CIdle</title><shortdesc>This document describes how to use the CIdle class to implement |
|
14 long running background tasks.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <p>An instance of the <codeph>CIdle</codeph> class, an idle time active object, |
|
16 can be used to perform low-priority processing when no higher-priority active |
|
17 objects are ready to run. </p> |
|
18 <p>An idle time active object together with its associated callback function |
|
19 may be used to implement potentially long running background tasks, such as |
|
20 spreadsheet recalculation and word processor repagination. </p> |
|
21 <p>A typical example is a background re-calculation in a spreadsheet. Assume |
|
22 that the spreadsheet is encapsulated by some class <codeph>CSheet</codeph>. </p> |
|
23 <codeblock id="GUID-01DE940E-BAA9-51C6-A6B2-5B251382428B" xml:space="preserve">class CSheet |
|
24 { |
|
25 ... |
|
26 TInt LaunchReCalcL(); |
|
27 TInt DoBackgroundRecalc(); |
|
28 static TInt BackgroundRecalc(TAny *aSheet); |
|
29 ... |
|
30 private: |
|
31 CIdle* iRecalc; |
|
32 ... |
|
33 };</codeblock> |
|
34 <p>Assume that a <codeph>CSheet</codeph> object has been created and that, |
|
35 as a result of user interaction or some other event, a background re-calculation |
|
36 is launched by a call to <codeph>LaunchReCalc()</codeph>. The implementation |
|
37 of this function would construct a <codeph>CIdle</codeph> object, specifying |
|
38 a suitably low priority. The value <codeph>CActive::EPriorityIdle</codeph> is |
|
39 recommended: </p> |
|
40 <codeblock id="GUID-20F61F7A-325B-53AA-B51F-575EA69B6CD3" xml:space="preserve">TInt CSheet::LaunchReCalcL() |
|
41 { |
|
42 ... |
|
43 if (!(iRecalc)) |
|
44 { |
|
45 iRecalc = CIdle::NewL(CActive::EPriorityIdle); |
|
46 } |
|
47 ... |
|
48 iRecalc->Start(TCallBack(BackgroundRecalc,this)); |
|
49 ... |
|
50 };</codeblock> |
|
51 <p>To start the background recalculation which is performed by the <codeph>DoBackGroundRecalc()</codeph> member |
|
52 function of <codeph>CSheet</codeph>, start by coding: </p> |
|
53 <codeblock id="GUID-08FC5576-EFA4-5527-851E-9E03531ED596" xml:space="preserve">iRecalc->Start(TCallBack(BackgroundRecalc,this));</codeblock> |
|
54 <p> <codeph>CIdle::Start()</codeph> requires a <codeph>TCallBack</codeph> object |
|
55 to encapsulate the function to be called and a pointer to be passed as a parameter |
|
56 to that function. As the encapsulated function must either be static or a |
|
57 non-member function, the easiest way to handle this is to pass the static |
|
58 function <codeph>BackgroundRecalc()</codeph> and a pointer to the sheet object |
|
59 itself. <codeph>BackgroundRecalc()</codeph> then calls the non-static <codeph>DoBackgroundRecalc()</codeph>: </p> |
|
60 <codeblock id="GUID-A4122F78-A32B-5592-9A65-B05EDBF30EF5" xml:space="preserve">TInt Sheet::BackgroundRecalc(TAny* aSheet) |
|
61 { |
|
62 return ((CSheet*)aSheet)->DoBackgroundRecalc(); |
|
63 }</codeblock> |
|
64 <p> <codeph>BackgroundRecalc()</codeph> is called when there are no higher |
|
65 priority active objects with events to process. It does a small amount of |
|
66 recalculation before returning. </p> |
|
67 <p>If the function has further work to do, it returns a true value to ensure |
|
68 that it is called again when there is no other higher priority event to handle. |
|
69 When the function finally completes its recalculation task, it returns a false |
|
70 value; the function is not called again. </p> |
|
71 <p>Typically, an object such as <codeph>CSheet</codeph> or some other object |
|
72 accessible from <codeph>CSheet</codeph>, keeps track of the state of the re-calculation. </p> |
|
73 <p>It is important for application responsiveness that each iteration of the |
|
74 idle time object take only a short time. All other events handled by the active |
|
75 scheduler, even high-priority ones, cannot be processed until the idle time |
|
76 object's callback function returns. </p> |
|
77 <p>When the background recalculation is complete, the callback function is |
|
78 not called again. The idle time active object can be destroyed or left until |
|
79 needed again. </p> |
|
80 <p>If <codeph>Cancel()</codeph> is called, the callback function is not called |
|
81 again. An application would need to implement appropriate cleanup. </p> |
|
82 </conbody></concept> |