Heap +Management Guide

Purpose

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.

Description

The following are the Heap management +APIs:

Heap Management is provided +by RHeap
RAllocator is +the base class for RHeap

There are three User functions that implement +the RHeap functionality, they are shown here:

To allocate a block +of memory: User:: AllocL()
To free a block of allocated +memory: User::Free() (Do not attempt to use this block +of memory again).
To manage an allocated +block of memory to either grow or shrink the memory block as required: User::ReAlloc(). +This will preserve the data of the allocated block and move it into the new +resized block.

Managing Heaps

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.

Accessing +Heap

A constant unsigned integer RHeapMinCellSize 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 (EKERN.EXE) as well as from the +user side (EUSER.DLL). This can be configured during +the rom build time using patchdata (tool support). An entry needs to be added +in OBY / IBY file.

Heap +Balancing

Memory heap balancing controls a size of a plurality +of memory heaps. The macros __UHEAP_MARK and __UHEAP_MARKEND 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.

__UHEAP_MARK +- to record the number of cells allocated in the heap

__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

Monitoring Memory Leaks

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.

How +it works

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.

The +traces are enabled by the use of a special shim library eexe_monitor_heap.lib 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.

Using Heap Manager

Memory management is provided +through the RHeap memory allocator implementation, an implementation +of RAllocator. In most cases though you would use the User +functions that implement the RHeap functions, which are far +easier to use. Much of the overhead involved in using RHeap directly +is hidden away under the User implementation.

Use +the heap manager to:

allocate memory blocks
release memory blocks +that are no longer required by the program
return the number of +blocks and the number of bytes currently allocated.
return the number of +bytes that are unused and the largest allocation that would succeed without +requesting more pages of memory.
change the size of the +allocated memory block.

Allocate a memory block

User::Alloc() Is +used to allocate a block of memory of the size indicated by the single parameter.

Usage

Use User::AllocL() to:

allocate and commit +a region of the size requested.

Free +allocated memory

User::Free() Is used to release +a block of memory that had previously been allocated. Once freed a program +cannot use the same physical memory block.

Usage

Use User::Free() to:

release an allocated +block of memory.

Modify +allocated memory

User::ReAlloc() Is used to +allocate a block of memory of the size indicated by the single parameter.

Usage

Use User::ReAllocL() to:

change the current size +of an allocated memory block.