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-E93E577A-0BDF-5472-B79F-DA60841C30CC" xml:lang="en"><title>Cleanup

    13 requirements</title><shortdesc>This document describes the requirements for cleanup after a function

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

    15 <p>When a function leaves, it transfers control directly to the statement

    16 following the <codeph>TRAP</codeph> (or <codeph>TRAPD</codeph>) macro under

    17 which it was invoked. This is carried out by setting the stack pointer to

    18 the context of the original <codeph>TRAP</codeph> macro, and jumping to the

    19 desired program location. Therefore,</p>

    20 <ul>

    21 <li id="GUID-FFC56E72-DCCD-5B0C-BDF4-41EE76BB808E"><p>any objects created

    22 as automatic variables, passed by value as arguments, or created as member

    23 variables of other objects so created, will be <keyword>orphaned</keyword>:

    24 their destructor will not be called, and any resources they claim except for

    25 storage space on the stack, cannot be recovered.</p> </li>

    26 </ul>

    27 <p>This key aspect of Symbian platform exceptions has far-reaching implications:</p>

    28 <ul>

    29 <li id="GUID-587C3891-CE53-5F83-96E9-94E17E869CBA"><p>There should be a clear

    30 distinction between objects which can be safely orphaned, and those which

    31 cannot. </p> <p>This is embodied in the naming convention for types. All types

    32 beginning with <codeph>T</codeph> can be safely orphaned, including, for instance, <codeph>TInt</codeph>, <codeph>TPoint</codeph>, <codeph>TPtr</codeph> and many others. Such objects can be freely allocated on the stack.</p> <p>The

    33 basic requirement for <codeph>T</codeph> objects is that all their data is

    34 contained internally. Pointers, handles and references to data owned by the <codeph>T</codeph> object

    35 are not allowed (although such references to data owned by other objects is

    36 allowed).</p> <p><codeph>C</codeph> objects must never be orphaned: they should

    37 never be allocated on the stack.</p> <p><codeph>R</codeph> objects may contain

    38 handles to external resources, but are generally designed so that the R object

    39 can be copied without copying its resources. Copied <codeph>R</codeph> objects

    40 may therefore be allocated on the stack: the stack-allocated copies may safely

    41 be orphaned, provided the resources are safely accessible by some other means.</p> </li>

    42 </ul>

    43 <ul>

    44 <li id="GUID-9550E9C4-F908-5AED-9294-8D74D73AA3CE"><p>Objects which cannot

    45 be safely orphaned must, if allocated inside the trap harness, be accessible

    46 somehow so they can be cleaned up. </p> </li>

    47 </ul>

    48 <p>The <i>cleanup stack</i> is the Symbian platform mechanism for handling

    49 this last problem. </p>

    50 <section id="GUID-459CE643-4A19-41E2-8251-92F0EA6A5C7D"><title>Example</title> <p>The problem for heap-allocated resources

    51 is shown below. If the call to <codeph>DoSomethingL()</codeph> leaves, the <codeph>CExample</codeph> object

    52 would be <keyword>orphaned</keyword> on the heap: the memory used for it could

    53 not have been recovered until the program terminates.</p> <codeblock id="GUID-475F1498-F050-5F2B-A1DE-81AA4F9323F2" xml:space="preserve">void doExampleL()

    54  {

    55  // An T-type object: can be declared on the stack

    56  TBuf<10> buf;

    57 

    58  // A C-type object: must be allocated on the heap

    59  // Allocate and leave if can not

    60  CExample* myExample = new (ELeave) CExample;

    61 

    62  // do something that cannot leave: no protection needed

    63  myExample->iInt = 5; 

    64 

    65  // PROBLEM: do something that can leave

    66  myExample->DoSomethingL();

    67    

    68  // delete

    69  delete myExample;

    70  }</codeblock> </section>

    71 </conbody></concept>