<?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-F686965A-13E5-5C0A-AED1-55EC91C79433" xml:lang="en"><title>Restrictions
on the use of leaves and TRAPs in destructors</title><shortdesc>Outlines the restrictions on the use of leaves and TRAPs in destructors.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>You <i>cannot</i> use <xref href="GUID-3F2CDC74-2568-371C-9D8E-34A66A619226.dita"><apiname>TRAP</apiname></xref> (and <xref href="GUID-57895C34-AD00-35E1-9BF8-478653056383.dita"><apiname>TRAPD</apiname></xref>)
and <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-ABF0FC5C-3334-3761-893D-D836B2EE0541"><apiname>User::Leave()</apiname></xref> in a destructor, nor in any function
that a destructor might call, for objects that have been placed onto the call
stack. <xref href="GUID-3F2CDC74-2568-371C-9D8E-34A66A619226.dita"><apiname>TRAP</apiname></xref> and <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-ABF0FC5C-3334-3761-893D-D836B2EE0541"><apiname>User::Leave()</apiname></xref> are implemented
in terms of C++ Try, Catch and Throw. This means that if an exception occurs,
the call stack is "unwound". In doing this, the destructors of objects on
the call stack are called. If any of these destructors subsequently throw
an exception, this is termed a nested exception. While a nested exception
is supported on the emulator (WINS), it is not supported on other hardware,
and there is no guarantee that the thread will terminate cleanly. </p>
<p>Symbian coding standards state that objects placed onto the call stack
should not have non-trivial destructors. By convention, such classes are identified
by names having an initial T or R. This means that such destructors should
not leave. </p>
<p>The following code fragment shows the kind of code that is <i>not safe</i> to
use: </p>
<codeblock id="GUID-7B2BD496-6F99-5586-B320-DB7C5DC490B9" xml:space="preserve">void f()  
    {
    TBar bar;
    // Function processing.
    ...
    // The bar object on the call stack is automatically destroyed
    // at function termination.
    }

TBar::~TBar()
    {
    // The destructor calls a function that can leave.
    // This is not permitted here.
    doCleanUpL();
    }</codeblock>
<p>You <i>can</i> use <xref href="GUID-3F2CDC74-2568-371C-9D8E-34A66A619226.dita"><apiname>TRAP</apiname></xref> (and <xref href="GUID-57895C34-AD00-35E1-9BF8-478653056383.dita"><apiname>TRAPD</apiname></xref>)
and <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-ABF0FC5C-3334-3761-893D-D836B2EE0541"><apiname>User::Leave()</apiname></xref> in a destructor and in any function that
a destructor might call, for heap-based objects, i.e. objects that are destroyed
by the cleanup stack. However, while this is permissible, it is not recommended
practice. </p>
<p>Such objects are instances of classes derived from <xref href="GUID-8F6FE089-E2A8-30F4-B67E-10F286347681.dita"><apiname>CBase</apiname></xref>,
and by convention such classes are identified by names having have an initial
C. </p>
<p>In principle, a destructor should never fail. If a destructor can leave,
or a function called by the destructor can leave, it suggests that the code
has been poorly architected. It also implies that part of the destruction
process might fail, potentially leading to memory or handle leaks. </p>
<p>One possible approach to avoid using functions that can leave within a
destructor is to have what might be referred to as ‘two-phase destruction’
where some form of <codeph>ShutdownL</codeph> function is called prior to
deleting the object. If there are concerns about introducing additional complexities
in API-usage (and greater risk), suitable guards can be introduced. One method
might be to store the current state of the object internally and then use
an ASSERT to check this in the destructor. This would ensure that any usage
errors are discovered by very simple run time testing. </p>
<p>The following code fragment shows an example of two-phase destruction. </p>
<codeblock id="GUID-BA3B57D6-913F-5AEC-A7AB-4EE6B915127A" xml:space="preserve">// Here, the shutdown function is a member of the class CMyClass,
// and performs destruction activity that can leave.

class CMyClass : public CBase
    {
public :
    IMPORT_C ~CMyClass();
    IMPORT_C void ShutdownL();
    ...
private :
    TBool iStateActive
    ...
    }

EXPORT_C void CMyClass::ShutdownL()
    {
       if (iStateActive == ETrue)
              {
              // Some destruction activity that can leave.
              iStateActive = EFalse;
              }
    }

EXPORT_C CMyClass::~CMyClass()
    {
       // Assert to ensure that ShutdownL() has already been called.
       ASSERT(iStateActive == EFalse);
    }
</codeblock>
</conbody></concept>