<?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-6D8460DF-8B0F-5249-B236-92ABE0E67A14" xml:lang="en"><title>Memory

Allocation Overview</title><shortdesc>Provides low-level functionality by which a Symbian platform process

can access and manipulate memory areas.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-B6FA381B-2A42-4D5A-9511-DC634E8AF6C2"><title>Purpose</title> <p>Most client programs do not

need to use this functionality directly. They are used by programs that are

explicitly concerned about sharing memory areas between threads within a process,

or between processes. </p> </section>

<section id="GUID-39581657-1B46-436B-A8F2-A3F7AB525DA4"><title>Description</title> <p>The API has two key concepts: chunk

and heap. </p> <p><b>Chunk</b> </p> <p>A

chunk defines a contiguous region of virtual addresses. It represents memory

that is addressable by running code. A chunk is the fundamental way in which

Symbian platform allocates memory and makes it available to running code. </p> <p>The

range of addressable memory is also referred to as <i>reserved</i> memory. </p> <p>Physical

addresses representing either memory storage like RAM, or memory-mapped I/O

devices, are mapped into a subset of a chunk's reserved memory. Such memory

is said to be <i>committed</i>. </p> <p>When a process is created, it contains

at least two chunks: </p> <ul>

<li id="GUID-143BBF82-BAA5-5548-83AC-54DF2067C058"><p>a chunk that contains: </p> <ul>

<li id="GUID-2A57D6BD-83FD-5C4B-B5AC-CA1BACDD5CB7"><p>the process executable's <codeph>.data</codeph> section

(initialised global and writable static data) </p> </li>

<li id="GUID-F6D7AB82-BEB5-5052-9723-B190F12A47ED"><p>the process executable's <codeph>.bss</codeph> section

(zero filled data) </p> </li>

<li id="GUID-DC6E22B6-9E12-5181-99DB-D6C2154C513A"><p>user-side stack space

for all threads that run in that process. </p> </li>

</ul> </li>

<li id="GUID-73016FAD-8F84-596C-B048-CD1E1B05AA8B"><p>a chunk to contain the

heap used by the main thread of the process. </p> </li>

</ul> <p>If the process executable is loaded into RAM (i.e. it is not ROM

resident), then there is another chunk to contain the code. </p> <p>On ARM

processors up to and including those that support the ARMv5 architecture,

the memory model used by Symbian platform is the <i>moving memory model</i>.

To guarantee real-time behaviour using this model, each process is limited

to a maximum of 16 chunks. This means that a program can create up to 14 additional

chunks. Where the process executable is loaded into RAM, the chunk containing

the code is effectively global and does not contribute to the 16 chunk per

process limit. </p> <p>On ARM processors that support the ARMv6 architecture,

the memory model used by Symbian platform is the <i>multiple memory model</i>.

Using this model, there is no limit on the number of chunks per process. Where

the process executable is loaded into RAM, the chunk containing the code is

specific to the process. </p> <p> <xref href="GUID-DA41F070-0E54-3F8A-B301-39A0C6AFAB38.dita"><apiname>TFindChunk</apiname></xref> is used for

finding a global chunk created by another process. </p> <p>The user-side interface

to a chunk is provided by an instance of the <xref href="GUID-326A2F4D-0E99-31C0-A35D-E8BF45913F07.dita"><apiname>RChunk</apiname></xref> class. </p> <p><b>Heap</b> </p> <p>A heap is used for explicit dynamic allocation of memory.

Symbian platform defines C++'s <codeph>new</codeph> operator to create objects

on the current thread's heap. </p> <p>Heaps may be: </p> <ul>

<li id="GUID-1ADAF0B8-BB72-5D07-BEA9-359DEFFC25E3"><p>monitored for memory

leaks: this happens automatically for GUI applications </p> </li>

<li id="GUID-0F5F3E02-F1E1-56D0-9865-D3DFA440DCF0"><p>shared between threads

within a process </p> </li>

<li id="GUID-ED409A70-ECD3-5EE9-9245-42FDEF5CCA42"><p>accessed and manipulated

at the cell level </p> </li>

</ul> <p>The heap interface is provided by the <xref href="GUID-9DB4A58C-6FC8-3292-A547-4C161BD188FC.dita"><apiname>RAllocator</apiname></xref> and <xref href="GUID-C5475104-B67A-3722-B11D-DBB930423492.dita"><apiname>MAllocator</apiname></xref> classes.

This interface is abstract so that device manufacturers can implement heaps

with different allocation algorithms. Symbian platform provides the <xref href="GUID-EFAFDD75-7E59-306A-882D-317F5564979E.dita"><apiname>RHeap</apiname></xref> class

as a default heap implementation. In practice, there is no need to know about

implementation details. </p> <p>When managing the current thread's heap, it

is more convenient to use the equivalent functions provided by the System

Static Functions API; this is the <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita"><apiname>User</apiname></xref> class. For example, <xref href="GUID-C197C9A7-EA05-3F24-9854-542E984C612D.dita#GUID-C197C9A7-EA05-3F24-9854-542E984C612D/GUID-C035F07D-B6D9-3A21-A323-DAC89137280D"><apiname>User::AllocL()</apiname></xref>.

The System Static Functions API also provides macros that conveniently wrap

calls for monitoring heap usage for memory leaks. </p> </section>

<section id="GUID-7A3524D6-AA39-49A2-9DBC-E3EAEA654A7B"><title>See also</title> <p> <xref href="GUID-506642C2-A14F-55F2-9377-43DDB14F4053.dita">Raw

Memory Overview</xref>  </p> <p> <xref href="GUID-FF8F5D97-7D37-5F6B-84A3-C064E2FD53E0.dita">System

Static Functions Overview</xref>  </p> <p> <xref href="GUID-5D4B86D3-20C4-5D87-A6C1-225018D32347.dita">Thread

And Process Management Overview</xref>  </p> </section>