<?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-&gt;iInt = 5; // cannot leave: no protection needed

 // do something that can leave: use cleanup stack
 CleanupStack::PushL(myExample); // pointer on cleanup stack
 myExample-&gt;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>
</conbody></concept>