<?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-CFA21FBA-593F-58DB-AADA-C9D6D676AEEE" xml:lang="en"><title>How

to share heaps</title><shortdesc>Heaps may be shared between threads within a process.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>When a new thread is created:</p>

<ul>

<li id="GUID-7FF23B75-DADB-557C-B8F7-C1884E51FCE4"><p>it can use the same

heap as the thread which is doing the creating.</p> </li>

<li id="GUID-19F6D491-9424-5320-BFF7-DFB27008D90B"><p>it can use the heap

which has been explicitly created for it by the thread which is doing the

creating.</p> </li>

<li id="GUID-83CB8A55-DB7C-503C-8CB8-E206C918FF99"><p>it can use the heap

automatically created for it by the operating system.</p> </li>

</ul>

<p><i>Only in the first two cases is the heap being shared.</i> </p>

<p>Both are achieved by using the version of <codeph>RThread::Create()</codeph> prototyped

as:</p>

<codeblock id="GUID-7716A80C-634E-55A2-BB22-EEB621DFFA40" xml:space="preserve">TInt Create(const TDesC&amp; aName,

            TThreadFunction aFunction,

            TInt aStackSize,

            RHeap* aHeap,

            TAny* aPtr,

            TOwnerType aType=EOwnerProcess);</codeblock>

<p>If <codeph>aHeap</codeph> is <codeph>NULL</codeph>, the new thread uses

the same heap as the parent thread. For example:</p>

<codeblock id="GUID-0F13C320-55FD-5570-89EF-109023AD4F0A" xml:space="preserve">RThread t;

_LIT(KTxtShared1,"Shared1");

...             ...

TInt r=t.Create(KTxtShared1,

                threadEntryPoint,

                KDefaultStackSize,

                NULL,

                NULL);</codeblock>

<p>The calling thread can create a new heap using <codeph>User::ChunkHeap()</codeph> or <codeph>UserHeap::ChunkHeap()</codeph> (this

is the same function; the <codeph>User</codeph> class is derived from <codeph>UserHeap</codeph>)

and pass this heap to the <codeph>RThread::Create()</codeph> function. For

example:</p>

<codeblock id="GUID-9DC2E0EF-6606-54FC-A2DE-3987620784A9" xml:space="preserve">_LIT(KTxtShare,"Share");

_LIT(KTxtShared1,"Shared1");

...

RHeap* pH=User::ChunkHeap(KTxtShare,0x1000,0x100000);

RThread t;

TInt r=t.Create(KTxtShared1,

                threadEntryPoint,

                KDefaultStackSize,

                pH,NULL);</codeblock>

<p>The new heap is contained within its own chunk.</p>

<p>If the <i>creating</i> thread no longer has any interest in this explicitly

created heap, it can close it by calling <codeph>Close()</codeph>. Note that

the corresponding call to <codeph>Open()</codeph> was done automatically by <codeph>User::ChunkHeap()</codeph>.

The function <codeph>Open()</codeph> should be used to re-open the heap for

sharing; this increases the access count.</p>

<p>Note that <codeph>Open()</codeph> can only be called on a heap created

using <codeph>User::ChunkHeap()</codeph>.</p>

<p>The heaps which are created automatically for a thread should not be closed

with a call to <codeph>Close()</codeph> since the chunk in which the heap

is created contains the thread's stack as well as the heap. In this case,

if <codeph>Close()</codeph> is called the thread is panicked.</p>