<?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-56841E07-1A4A-5572-BF3F-F80069FD5D59" xml:lang="en"><title>How
to start active objects</title><shortdesc>This document describes how to start active objects.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>The following example code shows how active objects are started. While
the example shows the creation of an active scheduler, in UI applications,
an active scheduler is always provided. </p>
<ul>
<li id="GUID-4E857369-075A-5337-9152-0475DE0D41E9"><p>Create an instance of
the active scheduler, <codeph>exampleScheduler</codeph>. This is an instance
of a class derived from <xref href="GUID-B4C76104-EA1B-3FC3-A31E-86A976598171.dita"><apiname>CActiveScheduler</apiname></xref> and provides an <codeph>Error()</codeph> function
to handle leaves occurring in the active object <codeph>RunL()</codeph> function(s). </p> </li>
<li id="GUID-857D957B-E5C5-5C37-BEEA-F10B42B208B5"><p>Push <codeph>exampleScheduler</codeph> onto
the cleanup stack and install as the current active scheduler. </p> </li>
<li id="GUID-38C2AC92-6DFF-50A1-BE24-163ABBCD66BA"><p>Create an active object, <codeph>myActiveObject</codeph>,
and pass a pointer to the service provider as the parameter. Note that often,
the service provider may be constructed as part of the active object's own
construction processing. </p> </li>
<li id="GUID-2C390F94-0AF5-585C-BAB4-A8142DF87F56"><p>Issue a request using <codeph>IssueRequest()</codeph>. </p> </li>
<li id="GUID-A39EB27D-91AE-5932-ADCE-7E75ECCB042F"><p>Use <codeph>CActiveScheduler::Start()</codeph> to
start the active scheduler’s wait loop. At least one outstanding request is
necessary before the wait loop is started, otherwise the thread hangs. All
further request issuing and servicing occurs within this function. The wait
loop continues until one of the active objects’ <codeph>RunL()</codeph> requests
termination using <codeph>CActiveScheduler::Stop()</codeph>. </p> </li>
<li id="GUID-ADCBB62D-0A83-5D5B-915C-7F30D863943C"><p>Pop the active object,
the active scheduler and the example service provider from the clean-up stack,
and destroy. The code assumes that the active object does not take ownership
of the <codeph>CExampleServiceProvider</codeph> object and is not responsible
for its destruction. </p> </li>
</ul>
<codeblock id="GUID-1895F4F4-0EDF-5ADC-B3D7-FC792719299C" xml:space="preserve">LOCAL_C void doExampleL()
    {
        // Create and install the active scheduler
    CActiveScheduler* exampleScheduler=new (ELeave) CExampleScheduler;
    CleanupStack::PushL(exampleScheduler);
    CActiveScheduler::Install(exampleScheduler);

        // Create the service provider. Often, the
        // service provider is part of the active object
    CExampleServiceProvider* myServiceProvider=new (ELeave) CExampleServiceProvider;
    CleanupStack::PushL(myServiceProvider);

        // Create the active object and issue the
        // first asynchronous request
    CExampleActiveObject * myActiveObject=new (ELeave) CExampleActiveObject(myServiceProvider);
    CleanupStack::PushL(myActiveObject);
    myActiveObject-&gt;IssueRequest();

        // Now we can start the active scheduler
    CActiveScheduler::Start();

        // Remove the exampleScheduler and other
        // objects from cleanup stack and destroy them
    CleanupStack::PopAndDestroy(3);
    }</codeblock>
</conbody></concept>