<?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>