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 task

    11   PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

    12 <task id="GUID-69D916D3-ED05-58DA-BA42-CE4D7E4F6482" xml:lang="en"><title>Automatic

    13 Resource Management Class Templates Tutorial</title><abstract>The <codeph>LCleanedupX</codeph> class provide a means of automatically

    14 cleaning up local variables on scope exit. Variants are provided for cleaning

    15 up pointers, references, handles and arrays, as well as generic cleanup items.

    16 The user is able to define a cleanup strategy to clean up the resource on

    17 scope exit.</abstract><prolog><metadata><keywords/></metadata></prolog><taskbody>

    18 <prereq><p>Before beginning you must know the following: </p><ul>

    19 <li id="GUID-90A3678E-CB31-5817-AB27-C115AC486A3A"><p> <b> Clean-up Stratergy:</b> Cleanup

    20 strategies can be specified as an optional template parameter of the class

    21 templates for automatic resource management. </p> </li>

    22 </ul> </prereq>

    23 <steps-unordered>

    24 <step id="GUID-26218FF0-6994-4FD7-9609-357AFDB3C177"><cmd><b>Declaring an LCleanedupX object</b></cmd>

    25 <info><p>An <codeph>LCleanedupX</codeph> object is declared using one of the

    26 class template constructors. The type to be managed is declared as the first

    27 template parameter. An optional second template parameter can be declared

    28 to implement a non-default cleanup strategy. </p> <p>An example code snippet

    29 for declaring <codeph>LCleanedupX</codeph> class is shown below: </p> <codeblock id="GUID-B9DFC2F9-0C7A-5CCA-9125-FC165BFA6C1B" xml:space="preserve">class LCleanedupPtr

    30             {

    31             CTicker* ticker1 = new(ELeave) CTicker;

    32             LCleanedupPtr CManagedUserTwoPhase one(CManagedUserTwoPhase::NewL(ticker1));

    33 

    34             CTicker* ticker2 = new(ELeave) CTicker;

    35             LCleanedupPtr CManagedUserSinglePhase two(CManagedUserSinglePhase::NewL(ticker2));

    36         }

    37 </codeblock></info>

    38 </step>

    39 <step id="GUID-AF65DC71-78C1-4B4D-9546-A9F4921E89D9"><cmd><b>Disabling Automatic Cleanup</b></cmd>

    40 <info><p>An object that is being managed by an <codeph>LCleanedupX</codeph> class

    41 can be unmanaged by calling the <codeph>Unmanage()</codeph> method of the

    42 LCleanedupX class. </p> <p>The managing object can be accessed using the .

    43 operator as in the call to <codeph>Unmanage()</codeph>. The <codeph>Unmanage()</codeph> disables

    44 cleanup and yields the previously managed pointer so that it can be safely

    45 returned. </p> <p>An example code snippet is given below: </p> <codeblock id="GUID-75BA5FAF-4C81-5626-A1F6-8AF91FD5972E" xml:space="preserve">

    46         static CStringUserTwoPhase* NewL(const TDesC& aName)

    47             {

    48                 LCleanedupPtr CStringUserTwoPhase self(new(ELeave) CStringUserTwoPhase);

    49                 self->ConstructL(aName);

    50                 return self.Unmanage(); 

    51             }

    52 </codeblock></info>

    53 </step>

    54 <step id="GUID-B9F7C183-E92E-47D6-8A6E-A1E1A76C1253"><cmd><b>Accessing the managed object</b></cmd>

    55 <info><p>The managed object can be accessed using the -&gt; operator as in the

    56 call to <codeph>ConstructL()</codeph> </p> <codeblock id="GUID-2C82F4C0-9E02-51C5-BF51-2C05EACB424C" xml:space="preserve">self-&gt;ConstructL(aName);</codeblock></info>

    57 </step>

    58 <step id="GUID-D070D636-665B-4023-A81A-C5AB0A5390CB"><cmd><b>Passing the managed object to a function</b></cmd>

    59 <info><p>The managed object can be passed to a function by dereferencing the

    60 managing object. An example code snippet is given below: </p> <codeblock id="GUID-5E5A3A0C-77E4-520A-BD0A-031C7D3CAAFD" xml:space="preserve">

    61 void RegisterTicker(CTicker& aTicker)

    62     {

    63     (void)aTicker;

    64     }

    65 

    66 </codeblock><p>The <codeph>RegisterTicker</codeph> function defined above

    67 takes a <codeph>CTicker&amp;</codeph> argument. If we have a <codeph>LCleanedupPtr&lt;CTicker&gt;</codeph> as

    68 defined below, we can pass the <codeph>CTicker</codeph> object to the function

    69 by dereferencing as shown below in the code snippet: </p> <codeblock id="GUID-EC93EC4F-3D3E-5A70-A0E1-CF73475A7309" xml:space="preserve">

    70 LCleanedupPtr CTicker t(new(ELeave) CTicker);

    71 

    72 RegisterTicker(*t); // Takes a CTicker&

    73 </codeblock></info>

    74 </step>

    75 </steps-unordered>

    76 </taskbody><related-links>

    77 <link href="GUID-B1D5B680-00E3-5702-985A-94256180E2D8.dita"><linktext>Automatic

    78 Resource Management</linktext></link>

    79 <link href="GUID-B419D99E-8312-5336-9693-3ED8DFCD0559.dita"><linktext>Automatic

    80 Resource Management Tutorial</linktext></link>

    81 </related-links></task>