<?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-B67DB652-A489-55C7-A3A2-D00C43BE161E" xml:lang="en"><title>How

to handle completed requests</title><shortdesc>This document describes how an active scheduler handles a completed

request.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>When an asynchronous service provider signals completion of a request,

the active scheduler's wait completes. </p>

<p>The active scheduler scans those active objects whose active request flags

are set. The active objects are checked in priority order. It invokes the <codeph>RunL()</codeph> function

of the first active object whose request has completed. If there are no such

active objects then the signal cannot be identified and the active scheduler

raises a panic. </p>

<p>The <codeph>RunL()</codeph> function performs whatever processing is required

to complete the request, for example retrieving the results of the service

function and displaying them. It may also: </p>

<ul>

<li id="GUID-F3DBFA70-BDC7-5205-89B8-6FD52D60F7E6"><p>schedule another request,

for example, in a keyboard handler, a request for the next key press. </p> </li>

<li id="GUID-387D63C5-8A05-5281-B825-47673094F0CB"><p>terminate the active

scheduler by calling <xref href="GUID-B4C76104-EA1B-3FC3-A31E-86A976598171.dita#GUID-B4C76104-EA1B-3FC3-A31E-86A976598171/GUID-B59D1017-1D81-3D5E-B0A2-73FC9C06194B"><apiname>CActiveScheduler::Stop()</apiname></xref>. </p> </li>

</ul>

<p>If it is possible for the <codeph>RunL()</codeph> function to leave, then

the active object should implement the <codeph>RunError()</codeph> function. </p>

<p>The active scheduler traps any leave occurring in the <codeph>RunL()</codeph> function

and calls the active object's <codeph>RunError()</codeph> function, passing

it the leave code. <codeph>RunError()</codeph> has the opportunity to do appropriate

cleanup and, when complete, should return <codeph>KErrNone</codeph>. </p>

<p>If <codeph>RunError()</codeph> returns anything other than <codeph>KErrNone</codeph>,

then the <i>active scheduler</i>'s <codeph>Error()</codeph> function is called.

As the default implementation of <codeph>Error()</codeph> raises a panic,

then a <xref href="GUID-B4C76104-EA1B-3FC3-A31E-86A976598171.dita"><apiname>CActiveScheduler</apiname></xref> derived class <i>must</i> be defined

to implement a suitable <codeph>Error()</codeph> function. </p>

<p>It may be simpler to ensure that the active objects's <codeph>RunError()</codeph> function <i>always</i> returns <codeph>KErrNone</codeph>. </p>

</conbody></concept>