RHeap Class Reference

#include <e32cmn.h>

class RHeap : public RAllocator

Inherits from

Nested Classes and Structures

Public Member Type Definitions
typedefvoid(* TWalkFunc
Protected Attributes
TInt iAlign
TUint8 *iBase
TInt iChunkHandle
TAllocFail iFailType
RFastLock iLock
TInt iMaxLength
TInt iNestingLevel
TAny *iTestData
TUint8 *iTop
TInt iUnused1
TInt iUnused2
TInt iUnused3
Public Member Enumerations
enumanonymous { EDebugHdrSize }
enumanonymous { ECellAlignment }
enumanonymous { EFreeCellSize }
enumanonymous { EAllocCellSize }
enumTCellType { EGoodAllocatedCell, EGoodFreeCell, EBadAllocatedCellSize, EBadAllocatedCellAddress, ..., EBadFreeCellSize }
enumTDebugHeapId { EUser, EKernel }
enumTDebugOp { EWalk, EHybridHeap }
enumTDefaultShrinkRatios { EShrinkRatio1, EShrinkRatioDflt }
Public Member Functions
virtual UIMPORT_C TAny *Alloc(TInt)
virtual UIMPORT_C TIntAllocLen(const TAny *)
virtual UIMPORT_C TIntAllocSize(TInt &)
virtual UIMPORT_C TIntAvailable(TInt &)
virtual UIMPORT_C TIntCompress()
virtual UIMPORT_C TIntDebugFunction(TInt, TAny *, TAny *)
virtual UIMPORT_C voidFree(TAny *)
virtual UIMPORT_C TAny *ReAlloc(TAny *, TInt, TInt)
virtual UIMPORT_C voidReset()
Protected Member Functions
RHeap()
virtual UIMPORT_C TIntExtension_(TUint, TAny *&, TAny *)
Inherited Attributes
RAllocator::iAccessCount
RAllocator::iCellCount
RAllocator::iFlags
RAllocator::iHandleCount
RAllocator::iHandles
RAllocator::iTotalAllocSize
Inherited Enumerations
RAllocator:@5
RAllocator:TAllocDebugOp
RAllocator:TAllocFail
RAllocator:TDbgHeapType
RAllocator:TExtension_Op
RAllocator:TFlags
RAllocator:TReAllocMode
Inherited Functions
RAllocator::Align(TAny *)const
RAllocator::Align(TInt)const
RAllocator::AllocAligned(TInt,TInt)
RAllocator::AllocL(TInt)
RAllocator::AllocLC(TInt)
RAllocator::AllocZ(TInt)
RAllocator::AllocZL(TInt)
RAllocator::Base()const
RAllocator::Check()const
RAllocator::Close()
RAllocator::Count()const
RAllocator::Count(TInt &)const
RAllocator::DoClose()
RAllocator::FreeZ(TAny *&)
RAllocator::MaxLength()const
RAllocator::Open()
RAllocator::RAllocator()
RAllocator::ReAllocL(TAny *,TInt,TInt)
RAllocator::Size()const
RAllocator::__DbgCheckFailure()
RAllocator::__DbgGetAllocFail()
RAllocator::__DbgMarkCheck(TBool,TInt,const TDesC8 &,TInt)
RAllocator::__DbgMarkCheck(TBool,TInt,const TUint8 *,TInt)
RAllocator::__DbgMarkEnd(TInt)
RAllocator::__DbgMarkStart()
RAllocator::__DbgSetAllocFail(TAllocFail,TInt)
RAllocator::__DbgSetBurstAllocFail(TAllocFail,TUint,TUint)

Detailed Description

Represents the default implementation for a heap.

The heap itself is contained in a chunk and may be the only occupant of the chunk or may share the chunk.

The class contains member functions for allocating, adjusting, freeing individual cells and generally managing the heap.

The class is not a handle in the same sense that RChunk is a handle; i.e. there is no Kernel object which corresponds to the heap.

Member Type Definition Documentation

Typedef TWalkFunc

typedef void(*TWalkFunc

Member Attribute Documentation

iAlign

TInt iAlign[protected]

iBase

TUint8 *iBase[protected]

iChunkHandle

TInt iChunkHandle[protected]

iFailType

TAllocFail iFailType[protected]

iLock

RFastLock iLock[protected]

iMaxLength

TInt iMaxLength[protected]

iNestingLevel

TInt iNestingLevel[protected]

iTestData

TAny *iTestData[protected]

iTop

TUint8 *iTop[protected]

iUnused1

TInt iUnused1[protected]

iUnused2

TInt iUnused2[protected]

iUnused3

TInt iUnused3[protected]

Member Enumeration Documentation

Enum anonymous

Size of a free cell header.

EnumeratorValueDescription
EDebugHdrSizesizeof(SDebugCell)

Enum anonymous

The default cell alignment.

EnumeratorValueDescription
ECellAlignment8

Enum anonymous

Size of a free cell header.

EnumeratorValueDescription
EFreeCellSize4

Enum anonymous

Size of an allocated cell header in a release build.

EnumeratorValueDescription
EAllocCellSize4

Enum TCellType

Enum TDebugHeapId

EnumeratorValueDescription
EUser0

The heap is a user heap.

EKernel1

The heap is the Kernel heap.

Enum TDebugOp

EnumeratorValueDescription
EWalk128
EHybridHeap

Enum TDefaultShrinkRatios

EnumeratorValueDescription
EShrinkRatio1256
EShrinkRatioDflt512

Constructor & Destructor Documentation

RHeap ( )

RHeap()[protected, inline]

Member Function Documentation

Alloc ( TInt )

UIMPORT_C TAny *Alloc(TIntaSize)[virtual]

Reimplemented from MAllocator::Alloc(TInt)

Allocates a cell of the specified size from the heap.

If there is insufficient memory available on the heap from which to allocate a cell of the required size, the function returns NULL.

The cell is aligned according to the alignment value specified at construction, or the default alignment value, if an explict value was not specified.

The resulting size of the allocated cell may be rounded up to a value greater than aSize, but is guaranteed to be not less than aSize.

See also: KMaxTInt

Parameters
aSizeThe size of the cell to be allocated from the heap
Return Value
A pointer to the allocated cell. NULL if there is insufficient memory available.
Panic Codes
USER47 if the maximum unsigned value of aSize is greater than or equal to the value of KMaxTInt/2; for example, calling Alloc(-1) raises this panic.

AllocLen ( const TAny * )

UIMPORT_C TIntAllocLen(const TAny *aCell)const [virtual]

Gets the length of the available space in the specified allocated cell.

Parameters
aCellA pointer to the allocated cell.
Return Value
The length of the available space in the allocated cell.
Panic Codes
USER42 if aCell does not point to a valid cell.

AllocSize ( TInt & )

UIMPORT_C TIntAllocSize(TInt &aTotalAllocSize)const [virtual]

Gets the number of cells allocated on this heap, and the total space allocated to them.

Parameters
aTotalAllocSizeOn return, contains the total space allocated to the cells.
Return Value
The number of cells allocated on this heap.

Available ( TInt & )

UIMPORT_C TIntAvailable(TInt &aBiggestBlock)const [virtual]

Gets the total free space currently available on the heap and the space available in the largest free block.

Note that this function exists mainly for compatibility reasons. In a modern heap implementation such as that present in Symbian it is not appropriate to concern oneself with details such as the amount of free memory available on a heap and its largeset free block, because the way that a modern heap implmentation works is not simple. The amount of available virtual memory != physical memory and there are multiple allocation strategies used internally, which makes all memory usage figures "fuzzy" at best.

In short, if you want to see if there is enough memory available to allocate a block of memory, call Alloc() and if it succeeds then there is enough memory! Messing around with functions like this is somewhat pointless with modern heap allocators.

Parameters
aBiggestBlockOn return, contains the space available in the largest free block on the heap. Due to the internals of modern heap implementations, you can probably still allocate a block larger than this!
Return Value
The total free space currently available on the heap. Again, you can probably still allocate more than this!

Compress ( )

UIMPORT_C TIntCompress()[virtual]

Reimplemented from MAllocator::Compress()

Compresses the heap.

The function frees excess committed space from the top of the heap. The size of the heap is never reduced below the minimum size specified during creation of the heap.

Return Value
The space reclaimed. If no space can be reclaimed, then this value is zero.

DebugFunction ( TInt, TAny *, TAny * )

UIMPORT_C TIntDebugFunction(TIntaFunc,
TAny *a1 = NULL,
TAny *a2 = NULL
)[virtual]

Extension_ ( TUint, TAny *&, TAny * )

UIMPORT_C TIntExtension_(TUintaExtensionId,
TAny *&a0,
TAny *a1
)[protected, virtual]

Free ( TAny * )

UIMPORT_C voidFree(TAny *aPtr)[virtual]

Reimplemented from MAllocator::Free(TAny *)

Frees the specified cell and returns it to the heap.

Parameters
aPtrA pointer to a valid cell; this pointer can also be NULL, in which case the function does nothing and just returns.
Panic Codes
USER42 if aCell points to an invalid cell.

ReAlloc ( TAny *, TInt, TInt )

UIMPORT_C TAny *ReAlloc(TAny *aPtr,
TIntaSize,
TIntaMode = 0
)[virtual]

Increases or decreases the size of an existing cell in the heap.

If the cell is being decreased in size, then it is guaranteed not to move, and the function returns the pointer originally passed in aCell. Note that the length of the cell will be the same if the difference between the old size and the new size is smaller than the minimum cell size.

If the cell is being increased in size, i.e. aSize is bigger than its current size, then the function tries to grow the cell in place. If successful, then the function returns the pointer originally passed in aCell. If unsuccessful, then:

1. if the cell cannot be moved, i.e. aMode has the ENeverMove bit set, then the function returns NULL. 2. if the cell can be moved, i.e. aMode does not have the ENeverMove bit set, then the function tries to allocate a new replacement cell, and, if successful, returns a pointer to the new cell; if unsuccessful, it returns NULL.

Note that in debug mode, the function returns NULL if the cell cannot be grown in place, regardless of whether the ENeverMove bit is set.

If the reallocated cell is at a different location from the original cell, then the content of the original cell is copied to the reallocated cell.

If the supplied pointer, aCell is NULL, then the function attempts to allocate a new cell, but only if the cell can be moved, i.e. aMode does not have the ENeverMove bit set.

Note the following general points:

1. If reallocation fails, the content of the original cell is preserved.

2. The resulting size of the re-allocated cell may be rounded up to a value greater than aSize, but is guaranteed to be not less than aSize.

See also: RAllocator::TReAllocMode

Parameters
aPtrA pointer to the cell to be reallocated. This may be NULL.
aSizeThe new size of the cell. This may be bigger or smaller than the size of the original cell.
aModeFlags controlling the reallocation. The only bit which has any effect on this function is that defined by the enumeration ENeverMove of the enum RAllocator::TReAllocMode. If this is set, then any successful reallocation guarantees not to have changed the start address of the cell. By default, this parameter is zero.
Return Value
A pointer to the reallocated cell. This may be the same as the original pointer supplied through aCell. NULL if there is insufficient memory to reallocate the cell, or to grow it in place.
Panic Codes
USER42, if aCell is not NULL, and does not point to a valid cell.
USER47, if the maximum unsigned value of aSize is greater than or equal to KMaxTInt/2. For example, calling ReAlloc(someptr,-1) raises this panic.

Reset ( )

UIMPORT_C voidReset()[virtual]

Reimplemented from MAllocator::Reset()

Frees all allocated cells on this heap.