<?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<10> 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->iInt = 5; 

 // PROBLEM: do something that can leave

 myExample->DoSomethingL();

 // delete

 delete myExample;

 }</codeblock> </section>