--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/SDK/Source/GUID-24FD00A1-CD09-5845-ACD5-4E4FF25084B3.dita	Thu Jan 21 18:18:20 2010 +0000
@@ -0,0 +1,111 @@
+<?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-24FD00A1-CD09-5845-ACD5-4E4FF25084B3" xml:lang="en"><title>Heap
+Management Guide</title><shortdesc>This document describes Heap management. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<section id="GUID-55CC7147-D437-4579-ADD9-F8418E19E7AC"><title>Purpose</title> <p>The heap is the area of memory used for
+dynamic memory allocation. Each thread has a chunk which contains that thread's
+program stack. For the main thread of a process, this chunk also contains
+the thread's heap. A request for memory is allocated from this heap. </p> </section>
+<section id="GUID-D2FA14DD-D30F-4E7C-945B-BCD081FAFF3D"><title>Description</title> <p>The following are the Heap management
+APIs: </p> <ul>
+<li id="GUID-1CB48994-7F7D-5108-843B-ED0F7296F9E6"><p>Heap Management is provided
+by <xref href="GUID-EFAFDD75-7E59-306A-882D-317F5564979E.dita"><apiname>RHeap</apiname></xref>  </p> </li>
+<li id="GUID-A1551D95-6B6E-5CDA-A064-D2E0C9DCEEF2"><p> <xref href="GUID-9DB4A58C-6FC8-3292-A547-4C161BD188FC.dita"><apiname>RAllocator</apiname></xref> is
+the base class for <xref href="GUID-EFAFDD75-7E59-306A-882D-317F5564979E.dita"><apiname>RHeap</apiname></xref>  </p> </li>
+</ul> <p>There are three <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita"><apiname>User</apiname></xref> functions that implement
+the <codeph>RHeap</codeph> functionality, they are shown here: </p> <ol id="GUID-B67B7A5B-F895-5B08-9C37-490F5E853182">
+<li id="GUID-B62CFCE3-C729-558F-AD2E-B9F5B363D82E"><p>To allocate a block
+of memory: <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-96661CE0-03D4-3F0D-A725-4B5CD49CAD2D"><apiname>User:: AllocL()</apiname></xref> </p> </li>
+<li id="GUID-CF3BB275-A11F-52DB-9ABC-1D5C2AB95BC3"><p>To free a block of allocated
+memory: <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-A1B58B92-E9B2-3C0F-89B3-BA3230A1E14F"><apiname>User::Free()</apiname></xref> (Do not attempt to use this block
+of memory again). </p> </li>
+<li id="GUID-B992EBC5-3FAB-55F4-ACA0-701F58109BF6"><p>To manage an allocated
+block of memory to either grow or shrink the memory block as required: <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-076A396B-D9F1-3CB9-8D93-AF2E1D0C9415"><apiname>User::ReAlloc()</apiname></xref>.
+This will preserve the data of the allocated block and move it into the new
+resized block. </p> </li>
+</ol> </section>
+<section id="GUID-16FCE4DE-D650-423B-AAED-5AADCEA10B1E"><title>Managing Heaps</title> <p>Managing heaps is very important
+to the increase the efficiency of virtual memory usage when performing heap
+allocation. This reduces the virtual memory fragmentation caused by heap allocation.
+The best way to manage heaps is to increment the initially defined heaps to
+make an memory allocation. There by an entirely new heap is created. The newly
+created heap may be added to the pool of heaps from which an allocation may
+be made. The additional heaps are of a constant, relatively large, size thereby
+reducing the risk of virtual memory fragmentation. </p> <p><b>Accessing
+Heap</b> </p> <p>A constant unsigned integer <xref href="GUID-42DFD47A-05B0-3A63-B5E7-FDA41C701BF8.dita"><apiname>RHeapMinCellSize</apiname></xref> is
+defined to specify the minimum heap cell size that can be allocated and also
+the minimum size needed to split the cell and add it to free list. It is exported
+both from the kernel (<filepath>EKERN.EXE</filepath>) as well as from the
+user side (<filepath>EUSER.DLL</filepath>). This can be configured during
+the rom build time using patchdata (tool support). An entry needs to be added
+in OBY / IBY file. </p> <p><b> Heap
+Balancing</b> </p> <p>Memory heap balancing controls a size of a plurality
+of memory heaps. The macros <filepath>__UHEAP_MARK</filepath> and <filepath>__UHEAP_MARKEND</filepath> are
+used to enclose a section of code where you need to check whether the heap
+is balanced. The description of these defined macros are listed below. </p> <p>__UHEAP_MARK
+- to record the number of cells allocated in the heap </p> <p>__UHEAP_MARKEND
+- a panic occurs to indicating a memory leak, if the heap does not have the
+same number of cells allocated at the point of call </p> <p><b>Monitoring Memory Leaks</b> </p> <p>Monitoring heap usage for user-side
+processes is chosen by the Memory Monitor client and provides the client with
+data about the monitored processes dynamic memory usage of the following events:
+allocation, de-allocation, reallocation, allocation failure, reallocation
+failure, and heap corruption. </p> <p><b>How
+it works</b> </p> <p>The EUser library contains the dynamic memory allocation
+functions used by all applications on the device. These have been instrumented
+such that they can optionally output Binary Trace log events to a kernel-side
+buffer whenever the dynamic memory functions are called by an application. </p> <p>The
+traces are enabled by the use of a special shim library <filepath>eexe_monitor_heap.lib</filepath> which
+must be linked with the application which is to be monitored. At run-time,
+the Symbian OS Memory Monitor uses the ULogger tool to configure the Binary
+Trace system to record dynamic memory event traces from applications, and
+to retrieve the dynamic memory events from the BTrace buffer when they occur.
+These events are then made available to Client Analyser programs via a client/server
+interface upon request. The SOMM does not require any special code to be compiled
+into application and can be used on debug targets (real device and emulator)
+as well as release targets. </p> </section>
+<section id="GUID-9545237F-A0A6-4CB5-8D55-052A7FB1DEB6"><title>Using Heap Manager</title> <p>Memory management is provided
+through the <xref href="GUID-EFAFDD75-7E59-306A-882D-317F5564979E.dita"><apiname>RHeap</apiname></xref> memory allocator implementation, an implementation
+of <xref href="GUID-9DB4A58C-6FC8-3292-A547-4C161BD188FC.dita"><apiname>RAllocator</apiname></xref>. In most cases though you would use the User
+functions that implement the <codeph>RHeap</codeph> functions, which are far
+easier to use. Much of the overhead involved in using <codeph>RHeap</codeph> directly
+is hidden away under the <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita"><apiname>User</apiname></xref> implementation. </p> <p>Use
+the heap manager to: </p> <ul>
+<li id="GUID-599F41F7-9FB9-5220-A780-CDD7B5596989"><p>allocate memory blocks </p> </li>
+<li id="GUID-A28C8217-8577-5022-9625-E03122D306C0"><p>release memory blocks
+that are no longer required by the program </p> </li>
+<li id="GUID-B7625FD0-FB67-5FE6-9F2B-812AB807FC4B"><p>return the number of
+blocks and the number of bytes currently allocated. </p> </li>
+<li id="GUID-E680FD7A-F975-50F0-BD81-93D9EE6B73A8"><p>return the number of
+bytes that are unused and the largest allocation that would succeed without
+requesting more pages of memory. </p> </li>
+<li id="GUID-7C9B9299-914A-5B74-9DAB-05DAD1B96E84"><p>change the size of the
+allocated memory block. </p> </li>
+</ul> <p id="GUID-0FD6F35E-2EB8-56BA-995C-23304EEBD4E0"><b>Allocate a memory block</b> </p> <p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-67554CF1-F7D1-37E3-8088-1625B3FCEBB4"><apiname>User::Alloc()</apiname></xref> Is
+used to allocate a block of memory of the size indicated by the single parameter. </p> <p><b>Usage</b> </p> <p>Use <codeph>User::AllocL()</codeph> to: </p> <ul>
+<li id="GUID-E5972E33-7060-59A8-ABF3-8CC9E89F4670"><p>allocate and commit
+a region of the size requested. </p> </li>
+</ul> <p><b>Free
+allocated memory</b> </p> <p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-A1B58B92-E9B2-3C0F-89B3-BA3230A1E14F"><apiname>User::Free()</apiname></xref> Is used to release
+a block of memory that had previously been allocated. Once freed a program
+cannot use the same physical memory block. </p> <p><b>Usage</b> </p> <p>Use <codeph>User::Free()</codeph> to: </p> <ul>
+<li id="GUID-D390DE7A-BCBC-5762-977A-E14E2E0D49CF"><p>release an allocated
+block of memory. </p> </li>
+</ul> <p><b>Modify
+allocated memory</b> </p> <p> <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-076A396B-D9F1-3CB9-8D93-AF2E1D0C9415"><apiname>User::ReAlloc()</apiname></xref> Is used to
+allocate a block of memory of the size indicated by the single parameter. </p> <p><b>Usage</b> </p> <p>Use <codeph>User::ReAllocL()</codeph> to: </p> <ul>
+<li id="GUID-E737B5FF-ACC8-593F-9650-C73C69D8FC88"><p>change the current size
+of an allocated memory block. </p> </li>
+</ul> </section>
+</conbody><related-links>
+<link href="GUID-9636A30F-39EB-54E6-8125-4487D4002FE0.dita"><linktext>Memory  
+              Management</linktext></link>
+</related-links></concept>
\ No newline at end of file