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-72E1F91B-173B-5F45-B9FF-42FD5F45438C" xml:lang="en"><title>How

    13 to pop and destroy</title><shortdesc>This document describes how to pop and destroy objects on the cleanup

    14 stack.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    15 <p>In general, it is recommended that any objects which are accessed only

    16 through an automatic pointer are pushed onto the cleanup stack immediately,

    17 before being used, and only popped before they must be destroyed.</p>

    18 <p>You can use the single function <codeph>CleanupStack::PopAndDestroy()</codeph> to

    19 both pop the object from the cleanup stack and destroy it. This operation

    20 is the usual thing to do when an object on the cleanup stack has been finished

    21 with.</p>

    22 <codeblock id="GUID-0ED3A351-8346-5C1F-9945-FEFC975472A2" xml:space="preserve">void doExampleL()

    23  {

    24  // allocate and leave if could not

    25  CExample* myExample = new (ELeave) CExample;

    26 

    27  // this cannot leave - no protection needed

    28  myExample->iInt = 5; 

    29  

    30  // do something that might leave, protected by cleanup stack

    31  CleanupStack::PushL(myExample); // push pointer to stack

    32 

    33  myExample->DoSomethingL()); // something that might leave 

    34 

    35  // pop from cleanup stack, and destroy, in one operation

    36  CleanupStack::PopAndDestroy();  

    37  }</codeblock>

    38 <section id="GUID-FAEA7437-EAB9-4599-B0A3-F1CC195A5F55"><title>Note</title> <ul>

    39 <li id="GUID-602FC7DD-F172-5C09-A55F-18B3E0B7A0A6"><p><codeph>Pop()</codeph> on

    40 its own is nevertheless useful: it is safe to pop an object from the cleanup

    41 stack when you are sure that it will either be destroyed, or a reference stored

    42 to it, before any operations are performed on it which might leave. This way,

    43 an object can never be orphaned (which is our aim). In the former case, you

    44 get pop-and-destroy all in one, which it is worthwhile for the system to provide.

    45 In the latter case, you need to store a pointer. This is what happens, for

    46 instance, in two-phase construction.</p> </li>

    47 </ul> </section>

    48 </conbody></concept>