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

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

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

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

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

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

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

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

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

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

    22 have completed </p> </li>

    23 </ol>

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

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

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

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

    28  {

    29  // allocate with checking

    30  CExample* myExample = new (ELeave) CExample;

    31 

    32  // do something that cannot leave

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

    34 

    35  // do something that can leave: use cleanup stack

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

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

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

    39 

    40  // delete

    41  delete myExample;

    42  }</codeblock>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    57 </ul> </section>

    58 </conbody></concept>