--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-CFA21FBA-593F-58DB-AADA-C9D6D676AEEE.dita Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,68 @@
+<?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& 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>
\ No newline at end of file