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-8BD6B29C-D905-5D2B-992A-A04AAD9ABBE3" xml:lang="en"><title>Long-running

    13 services and background objects</title><shortdesc>This document describes the use of background objects to respond

    14 to requests for long-running services.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    15 <p>System responsiveness is important. Threads must be responsive to their

    16 users — a delay of more than a few hundred milliseconds is generally unacceptable.</p>

    17 <p>This implies that <i>all </i> <codeph>RunL()</codeph> <i> functions should

    18 complete in a few hundred milliseconds in order to maintain system responsiveness</i>.</p>

    19 <p>In some cases, servicing a request may take longer than this. For example,

    20 printing a document, or sending a file, may take seconds or minutes to execute,

    21 but they should not hold up the main thread. It should also be possible to

    22 cancel long running services.</p>

    23 <p>The preferred solution is to use a background active object running in

    24 the same thread as all other active objects </p>

    25 <p>With this approach, the long running service is split into multiple chunks.

    26 The <codeph>RunL()</codeph> function allows itself to run for a relatively

    27 short period and then renews its request. This background active object tracks

    28 its own progress through the long running task so that when <codeph>RunL()</codeph> is

    29 next called, the it can continue from where it finished last time.</p>

    30 <p>The background active object has a lower priority than other active objects

    31 in the thread. The user driven event-handling active objects can cancel the

    32 background active object by calling its <codeph>Cancel()</codeph> function.</p>

    33 <p>The advantages of this approach are:</p>

    34 <ul>

    35 <li id="GUID-CAA7ED85-1F45-5D1F-95FE-5A2606A0C27F"><p>active objects are very

    36 cheap to create and use very few resources.</p> </li>

    37 <li id="GUID-3BF548A8-D3FA-5718-AB91-14C556199E70"><p>co-operating active

    38 objects cannot pre-empt each other; therefore, there is no need for locking

    39 and synchronization primitives when programming with multiple active objects.</p> </li>

    40 <li id="GUID-7B8FCF9D-C24A-59E9-B0F7-D6E81E7DAF3F"><p>active objects can share

    41 resources that are owned by a thread.</p> </li>

    42 </ul>

    43 <p>The active object framework allows the active-object implementation of

    44 a long-running operation to be concealed from the API, so that the service

    45 is presented to the user simply as an asynchronous request function together

    46 with an associated cancel function.</p>

    47 <p>In cases where an active object implementation is impossible or impractical

    48 to program, then a background thread may be used to implement a long-running

    49 service. This approach is <i>not</i> recommended for code specifically designed

    50 for Symbian platform.</p>

    51 </conbody></concept>