<?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-E93E577A-0BDF-5472-B79F-DA60841C30CC" xml:lang="en"><title>Cleanup
requirements</title><shortdesc>This document describes the requirements for cleanup after a function
leaves.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>When a function leaves, it transfers control directly to the statement
following the <codeph>TRAP</codeph> (or <codeph>TRAPD</codeph>) macro under
which it was invoked. This is carried out by setting the stack pointer to
the context of the original <codeph>TRAP</codeph> macro, and jumping to the
desired program location. Therefore,</p>
<ul>
<li id="GUID-FFC56E72-DCCD-5B0C-BDF4-41EE76BB808E"><p>any objects created
as automatic variables, passed by value as arguments, or created as member
variables of other objects so created, will be <keyword>orphaned</keyword>:
their destructor will not be called, and any resources they claim except for
storage space on the stack, cannot be recovered.</p> </li>
</ul>
<p>This key aspect of Symbian platform exceptions has far-reaching implications:</p>
<ul>
<li id="GUID-587C3891-CE53-5F83-96E9-94E17E869CBA"><p>There should be a clear
distinction between objects which can be safely orphaned, and those which
cannot. </p> <p>This is embodied in the naming convention for types. All types
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
basic requirement for <codeph>T</codeph> objects is that all their data is
contained internally. Pointers, handles and references to data owned by the <codeph>T</codeph> object
are not allowed (although such references to data owned by other objects is
allowed).</p> <p><codeph>C</codeph> objects must never be orphaned: they should
never be allocated on the stack.</p> <p><codeph>R</codeph> objects may contain
handles to external resources, but are generally designed so that the R object
can be copied without copying its resources. Copied <codeph>R</codeph> objects
may therefore be allocated on the stack: the stack-allocated copies may safely
be orphaned, provided the resources are safely accessible by some other means.</p> </li>
</ul>
<ul>
<li id="GUID-9550E9C4-F908-5AED-9294-8D74D73AA3CE"><p>Objects which cannot
be safely orphaned must, if allocated inside the trap harness, be accessible
somehow so they can be cleaned up. </p> </li>
</ul>
<p>The <i>cleanup stack</i> is the Symbian platform mechanism for handling
this last problem. </p>
<section id="GUID-459CE643-4A19-41E2-8251-92F0EA6A5C7D"><title>Example</title> <p>The problem for heap-allocated resources
is shown below. If the call to <codeph>DoSomethingL()</codeph> leaves, the <codeph>CExample</codeph> object
would be <keyword>orphaned</keyword> on the heap: the memory used for it could
not have been recovered until the program terminates.</p> <codeblock id="GUID-475F1498-F050-5F2B-A1DE-81AA4F9323F2" xml:space="preserve">void doExampleL()
 {
 // An T-type object: can be declared on the stack
 TBuf&lt;10&gt; buf;

 // A C-type object: must be allocated on the heap
 // Allocate and leave if can not
 CExample* myExample = new (ELeave) CExample;

 // do something that cannot leave: no protection needed
 myExample-&gt;iInt = 5; 

 // PROBLEM: do something that can leave
 myExample-&gt;DoSomethingL();
   
 // delete
 delete myExample;
 }</codeblock> </section>
</conbody></concept>