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

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

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

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

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

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

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

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

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

with.</p>

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

 {

 // allocate and leave if could not

 CExample* myExample = new (ELeave) CExample;

 // this cannot leave - no protection needed

 myExample->iInt = 5; 

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

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

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

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

 CleanupStack::PopAndDestroy();  

 }</codeblock>

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

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

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

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

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

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

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

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

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

</ul> </section>

</conbody></concept>