<?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>
</conbody></concept>