<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-8BD6B29C-D905-5D2B-992A-A04AAD9ABBE3" xml:lang="en"><title>Long-running

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

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

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

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

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

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

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

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

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

cancel long running services.</p>

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

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

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

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

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

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

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

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

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

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

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

<ul>

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

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

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

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

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

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

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

</ul>

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

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

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

with an associated cancel function.</p>

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

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

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

for Symbian platform.</p>

</conbody></concept>