--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-14BBFDA8-7765-5939-9E47-36E299841F50.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,58 @@
+<?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>
\ No newline at end of file