<?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-18182059-859D-51CF-A940-D230D9F9CF8C" xml:lang="en"><title>How

to allocate and de-allocate cleanup stacks</title><shortdesc>This document describes when and how a cleanup stack should be

allocated and de-allocated.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The main categories of programs (GUI applications and servers) both have

cleanup stacks created for them as part of their respective frameworks. Simple

console programs for test and demonstration purposes though require a cleanup

stack to be explicitly allocated. </p>

<p>Allocate the stack at the beginning of the thread as follows:</p>

<codeblock id="GUID-204BB8EA-016F-53CA-BB22-17B685BFF18A" xml:space="preserve">TheTrapCleanup=CTrapCleanup::New();</codeblock>

<p>De-allocate the cleanup stack at the end of the thread as follows:</p>

<codeblock id="GUID-C8A45849-E86C-5DA6-B1A5-88113B06C2B7" xml:space="preserve">delete TheTrapCleanup;</codeblock>

<section id="GUID-9E86AB70-D551-4356-9001-749FBE8B2DCE"><title>Notes</title> <ul>

<li id="GUID-37929EEE-F608-5754-9324-6731FEA5B1B2"><p>This explicit allocation

and de-allocation is necessary for threads which use cleanup processing. Threads

which do not use cleanup stack processing need not allocate a cleanup stack. </p> </li>

<li id="GUID-6B30E7F5-1D29-50EF-8896-0CD8400BBBCF"><p>Note that the cleanup

stack variable name (<codeph>TheTrapCleanup</codeph> in this case) is only

used to reference the stack when it needs to be destroyed. Therefore the user

is at liberty to give the stack any valid variable name. Multiple cleanup

stacks are supported: the system holds a stack of cleanup stacks, of which

the top item is the current cleanup stack. As such, when a new stack is created

it is pushed onto the stack of cleanup stacks, making it the current cleanup

stack. When it is destroyed, it is pushed off the stack of cleanup stacks

making the previously stacked cleanup stack the current one.</p> </li>

</ul> </section>