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:

1. To allocate a block of memory: User:: AllocL()

2. To free a block of allocated memory: User::Free() (Do not attempt to use this block of memory again).

3. 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 platform 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.