--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-E93E577A-0BDF-5472-B79F-DA60841C30CC.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,71 @@
+<?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>
\ No newline at end of file