<?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>