<?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-14BBFDA8-7765-5939-9E47-36E299841F50" xml:lang="en"><title>How

to use the cleanup stack</title><shortdesc>This document describes how to use the cleanup stack when a function

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

<p>The cleanup stack is used as follows: </p>

<ol id="GUID-BAC73597-5165-55A6-B5E7-12FA156785DF">

<li id="GUID-9C056803-25F8-557C-B630-0B40D38EFABA"><p>Use <codeph>CleanupStack::PushL()</codeph> <b>  </b> to

push a pointer to the object onto the cleanup stack before any operation which

might leave is performed </p> </li>

<li id="GUID-F5F7946D-9E99-54B7-AF13-C76317296442"><p>Use <codeph>CleanupStack::Pop()</codeph> to

pop the pointer from the cleanup stack when all operations that might leave

have completed </p> </li>

</ol>

<p>If a function leaves, then part of leave processing is to pop <i>and destroy</i> all

objects on the cleanup stack. Thus, the cleanup stack may be used to prevent

objects becoming orphaned if a leave occurs. </p>

<codeblock id="GUID-4692E277-85DD-5178-B7AF-57539C9CA2E8" xml:space="preserve">void doExampleL()

 {

 // allocate with checking

 CExample* myExample = new (ELeave) CExample;

 // do something that cannot leave

 myExample->iInt = 5; // cannot leave: no protection needed

 // do something that can leave: use cleanup stack

 CleanupStack::PushL(myExample); // pointer on cleanup stack

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

 CleanupStack::Pop(); // it didn't leave: pop the pointer

 // delete

 delete myExample;

 }</codeblock>

<section id="GUID-9DCA8E7D-9F8B-4597-9743-1793458DCB9B"><title>Notes</title> <ul>

<li id="GUID-AFBFF014-D03C-56A5-AA09-EB7BCF54A22A"><p>The cleanup stack is

necessary here because the <codeph>CExample</codeph> would be orphaned on

the heap if a leave occurred. This is because the <codeph>CExample</codeph> is

referred to only by an automatic pointer <codeph>myExample</codeph>, which

itself becomes orphaned on the stack when the leave occurs. If the <codeph>CExample</codeph> ’s

address had been stored in an object which was <i>not</i> orphaned by the

leave, then it would not be necessary to use the cleanup stack to ensure that

it is cleaned up correctly. </p> </li>

<li id="GUID-2B0103C5-991E-54AF-B21C-E68205212510"><p>The <codeph>CleanupStack::PushL()</codeph> operation

itself may leave because more memory may be needed for more cleanup stack

frames. It is guaranteed that the object is pushed to the stack before any

attempt is made to allocate more stack space. Thus, a failure of <codeph>CleanupStack::PushL()</codeph> will

cause the object that was being pushed to be cleaned up properly. </p> </li>

</ul> </section>