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

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

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

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

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

are ready to run.</p>

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

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

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

    {

public:

    static CLibUnloader* NewL(RLibrary& aLibrary);

    inline void Unload();

protected:

    CLibUnloader();

    ~CLibUnloader();

    virtual void RunL();

private:

    RLibrary iLib;

    };</codeblock>

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

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

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

    {

    CLibUnloader* u=new(ELeave)CLibUnloader;

    u->iLib=aLibrary;

    return u;

    }</codeblock>

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

<ul>

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

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

     :CAsyncOneShot(E_a_very_low_priority)

     {}</codeblock> </li>

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

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

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()

    {

    Call();

    }</codeblock> </li>

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

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

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

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

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()

    {

    delete this;

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

    {

    Cancel();

    iLib.Close();

    }</codeblock> </li>

</ul>

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

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

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>

</conbody></concept>