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-837EF355-9154-506B-AE4F-4290FC9DBDC9" xml:lang="en"><title>Using

    13 CAsyncOneShot</title><shortdesc>This document descrbes the use of the <codeph>CAsyncOneShot</codeph> class

    14 in scheduling.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    15 <p>An instance of a class derived from the <xref href="GUID-619AF4A9-4DAF-3FA4-A704-717DB30B5389.dita"><apiname>CAsyncOneShot</apiname></xref> class

    16 can be used to perform one-off processing when no higher-priority active objects

    17 are ready to run.</p>

    18 <p>While it has many uses, a common usage is to use it to unload a library.

    19 A typical <codeph>CAsyncOneShot</codeph> derived class is defined as:</p>

    20 <codeblock id="GUID-6C063D5F-15FD-575E-8184-BED08FEE4BAA" xml:space="preserve">class CLibUnloader : public CAsyncOneShot

    21     {

    22 public:

    23     static CLibUnloader* NewL(RLibrary& aLibrary);

    24     inline void Unload();

    25 protected:

    26     CLibUnloader();

    27     ~CLibUnloader();

    28     virtual void RunL();

    29 private:

    30     RLibrary iLib;

    31     };</codeblock>

    32 <p>The static <codeph>NewL()</codeph> function takes a reference to an existing

    33 open <xref href="GUID-25327159-83D6-3507-B187-09EA4BB3727F.dita"><apiname>RLibrary</apiname></xref> object and creates a new <codeph>CLibUnloader</codeph> object:</p>

    34 <codeblock id="GUID-2D743CF1-106E-5051-83E7-FFBD9F55148E" xml:space="preserve">CLibUnloader* CLibUnloader::NewL(RLibrary&amp; aLibrary)

    35     {

    36     CLibUnloader* u=new(ELeave)CLibUnloader;

    37     u->iLib=aLibrary;

    38     return u;

    39     }</codeblock>

    40 <p>The remaining functions are implemented as follows:</p>

    41 <ul>

    42 <li id="GUID-CFE3C110-43B5-5E04-AACF-A6389EE374B5"><p>Constructor sets a low

    43 active object priority</p> <codeblock id="GUID-2961B2D0-E615-5529-9248-7389D3DE4E3E" xml:space="preserve">CLibUnloader::CLibUnloader()

    44      :CAsyncOneShot(E_a_very_low_priority)

    45      {}</codeblock> </li>

    46 <li id="GUID-6FCA9BDB-7D15-5AB6-B776-40BB18E17052"><p>Calling <codeph>Unload()</codeph> activates

    47 the active object; the active scheduler will call its <codeph>RunL()</codeph> function

    48 as soon as there are no other higher priority active objects ready to run.</p> <codeblock id="GUID-95E3596B-FC18-524E-B9EC-8F04702715A6" xml:space="preserve">void CLibUnloader::Unload()

    49     {

    50     Call();

    51     }</codeblock> </li>

    52 <li id="GUID-691CD813-6A05-5BCA-8B90-FFDEFA3623E6"><p>The active scheduler

    53 calls <codeph>RunL()</codeph>, which, in this example, simply deletes the

    54 active object. This causes the destructor to be called which closes the library.

    55 It also has the effect of removing the active object from the active scheduler

    56 through the <xref href="GUID-067293BF-B28C-3CEC-92F4-1351A795EA7F.dita"><apiname>CActive</apiname></xref> base class destructor. </p> <codeblock id="GUID-366FF87F-D994-5ED9-9DE8-0A195F4745D9" xml:space="preserve">void CLibUnloader::RunL()

    57     {

    58     delete this;

    59     }</codeblock> <codeblock id="GUID-DBBF0C78-A941-5B62-A89B-698EA5CFB972" xml:space="preserve">CLibUnloader::~CLibUnloader()

    60     {

    61     Cancel();

    62     iLib.Close();

    63     }</codeblock> </li>

    64 </ul>

    65 <p>In other uses of <xref href="GUID-619AF4A9-4DAF-3FA4-A704-717DB30B5389.dita"><apiname>CAsyncOneShot</apiname></xref>, <codeph>RunL()</codeph> could

    66 do more complex processing, and indeed could re-queue the active object with

    67 another call to <xref href="GUID-619AF4A9-4DAF-3FA4-A704-717DB30B5389.dita#GUID-619AF4A9-4DAF-3FA4-A704-717DB30B5389/GUID-A7955FDB-B030-392F-B5D8-13F7EEDF4337"><apiname>CAsyncOneShot::Call()</apiname></xref>. </p>

    68 </conbody></concept>