RHeap Class Reference

class RHeap : public RAllocator

Represents the default implementation for a heap.

The default implementation uses an address-ordered first fit type algorithm.

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

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.

Inherits from

Public Member Functions
RHeap ( TInt , TInt , TBool )
RHeap ( TInt , TInt , TInt , TInt , TInt , TInt , TBool )
TInt Align ( TInt )
const TAny * Align (const TAny *)
UIMPORT_C TAny * Alloc ( TInt )
UIMPORT_C TInt AllocLen (const TAny *)
UIMPORT_C TInt AllocSize ( TInt &)
UIMPORT_C TInt Available ( TInt &)
TUint8 * Base ()
TInt ChunkHandle ()
UIMPORT_C TInt Compress ()
UIMPORT_C TInt DebugFunction ( TInt , TAny *, TAny *)
UIMPORT_C void Free ( TAny *)
TBool IsLastCell (const SCell *)
void Lock ()
TInt MaxLength ()
UIMPORT_C TAny * ReAlloc ( TAny *, TInt , TInt )
UIMPORT_C void Reset ()
TInt Size ()
void Unlock ()
void operator delete ( TAny *, TAny *)
UIMPORT_C TAny * operator new ( TUint , TAny *)
Protected Member Functions
RHeap ()
void CheckCell (const SCell *)
TBool CheckForSimulatedAllocFail ()
SCell * DoAlloc ( TInt , SCell *&)
TInt DoCheckHeap ( SCheckInfo *)
TInt DoCountAllocFree ( TInt &)
void DoFree ( SCell *)
TUint32 DoMarkEnd ( TInt )
void DoMarkStart ()
void DoSetAllocFail ( TAllocFail , TInt )
void DoSetAllocFail ( TAllocFail , TInt , TUint )
UIMPORT_C TInt Extension_ ( TUint , TAny *&, TAny *)
void FindFollowingFreeCell ( SCell *, SCell *&, SCell *&)
UIMPORT_C SCell * GetAddress (const TAny *)
void Initialise ()
TAny * ReAllocImpl ( TAny *, TInt , TInt )
TInt Reduce ( SCell *)
TInt SetBrk ( TInt )
TInt TryToGrowCell ( SCell *, SCell *, SCell *, TInt )
TInt TryToGrowHeap ( TInt , SCell *)
void Walk ( TWalkFunc , TAny *)
void WalkCheckCell ( TAny *, TCellType , TAny *, TInt )
Inherited Functions
RAllocator::AllocL(TInt)
RAllocator::AllocLC(TInt)
RAllocator::AllocZ(TInt)
RAllocator::AllocZL(TInt)
RAllocator::Check()const
RAllocator::Close()
RAllocator::Count()const
RAllocator::Count(TInt &)const
RAllocator::DoClose()
RAllocator::FreeZ(TAny *&)
RAllocator::Open()
RAllocator::RAllocator()
RAllocator::ReAllocL(TAny *,TInt,TInt)
RAllocator::__DbgCheckFailure()
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)
Public Member Enumerations
enum TCellType {
EGoodAllocatedCell , EGoodFreeCell , EBadAllocatedCellSize , EBadAllocatedCellAddress , EBadFreeCellAddress , EBadFreeCellSize
}
enum TDebugHeapId { EUser  = 0, EKernel  = 1 }
enum TDebugOp { EWalk  = 128 }
enum TDefaultShrinkRatios { EShrinkRatio1  = 256, EShrinkRatioDflt  = 512 }
Inherited Enumerations
RAllocator:@10
RAllocator:TAllocDebugOp
RAllocator:TAllocFail
RAllocator:TDbgHeapType
RAllocator:TFlags
RAllocator:TReAllocMode
Public Member Type Definitions
typedef void(* TWalkFunc
Protected Attributes
TInt iAlign
TInt iAllocCount
TUint8 * iBase
TInt iChunkHandle
TInt iFailAllocCount
TInt iFailRate
TAllocFail iFailType
TBool iFailed
SCell iFree
TInt iGrowBy
RFastLock iLock
TInt iMaxLength
TInt iMinCell
TInt iMinLength
TInt iNestingLevel
TInt iOffset
TInt iPageSize
TInt iRand
TAny * iTestData
TUint8 * iTop
Inherited Attributes
RAllocator::iAccessCount
RAllocator::iCellCount
RAllocator::iFlags
RAllocator::iHandleCount
RAllocator::iHandles
RAllocator::iTotalAllocSize

Constructor & Destructor Documentation

RHeap(TInt, TInt, TBool)

UIMPORT_C RHeap ( TInt aMaxLength,
TInt aAlign = 0,
TBool aSingleThread = ETrue
)

Parameters

TInt aMaxLength
TInt aAlign = 0
TBool aSingleThread = ETrue

RHeap(TInt, TInt, TInt, TInt, TInt, TInt, TBool)

UIMPORT_C RHeap ( TInt aChunkHandle,
TInt aOffset,
TInt aMinLength,
TInt aMaxLength,
TInt aGrowBy,
TInt aAlign = 0,
TBool aSingleThread = EFalse
)

Parameters

TInt aChunkHandle
TInt aOffset
TInt aMinLength
TInt aMaxLength
TInt aGrowBy
TInt aAlign = 0
TBool aSingleThread = EFalse

RHeap()

RHeap ( ) [protected, inline]

Member Functions Documentation

Align(TInt)

TInt Align ( TInt a ) const [inline]

Parameters

TInt a

Align(const TAny *)

const TAny * Align ( const TAny * a ) const [inline]

Parameters

const TAny * a

Alloc(TInt)

UIMPORT_C TAny * Alloc ( TInt aSize ) [virtual]

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.

panic
USER 47 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.
KMaxTInt

Parameters

TInt aSize The size of the cell to be allocated from the heap

AllocLen(const TAny *)

UIMPORT_C TInt AllocLen ( const TAny * aCell ) const [virtual]

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

panic
USER 42 if aCell does not point to a valid cell.

Parameters

const TAny * aCell A pointer to the allocated cell.

AllocSize(TInt &)

UIMPORT_C TInt AllocSize ( TInt & aTotalAllocSize ) const [virtual]

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

Parameters

TInt & aTotalAllocSize On return, contains the total space allocated to the cells.

Available(TInt &)

UIMPORT_C TInt Available ( TInt & aBiggestBlock ) const [virtual]

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

The space available represents the total space which can be allocated.

Note that compressing the heap may reduce the total free space available and the space available in the largest free block.

Parameters

TInt & aBiggestBlock On return, contains the space available in the largest free block on the heap.

Base()

TUint8 * Base ( ) const [inline]

Gets a pointer to the start of the heap.

Note that because of the small space overhead incurred by all allocated cells, no cell will have the same address as that returned by this function.

CheckCell(const SCell *)

void CheckCell ( const SCell * aCell ) const [protected]

Parameters

const SCell * aCell

CheckForSimulatedAllocFail()

TBool CheckForSimulatedAllocFail ( ) [protected]

ChunkHandle()

TInt ChunkHandle ( ) const [inline]

Compress()

UIMPORT_C TInt Compress ( ) [virtual]

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.

DebugFunction(TInt, TAny *, TAny *)

UIMPORT_C TInt DebugFunction ( TInt aFunc,
TAny * a1 = NULL,
TAny * a2 = NULL
) [virtual]

Parameters

TInt aFunc
TAny * a1 = NULL
TAny * a2 = NULL

DoAlloc(TInt, SCell *&)

SCell * DoAlloc ( TInt aSize,
SCell *& aLastFree
) [protected]

Parameters

TInt aSize
SCell *& aLastFree

DoCheckHeap(SCheckInfo *)

TInt DoCheckHeap ( SCheckInfo * aInfo ) [protected]

Parameters

SCheckInfo * aInfo

DoCountAllocFree(TInt &)

TInt DoCountAllocFree ( TInt & aFree ) [protected]

Parameters

TInt & aFree

DoFree(SCell *)

void DoFree ( SCell * pC ) [protected]

Parameters

SCell * pC

DoMarkEnd(TInt)

TUint32 DoMarkEnd ( TInt aExpected ) [protected]

Parameters

TInt aExpected

DoMarkStart()

void DoMarkStart ( ) [protected]

DoSetAllocFail(TAllocFail, TInt)

void DoSetAllocFail ( TAllocFail aType,
TInt aRate
) [protected]

Parameters

TAllocFail aType
TInt aRate

DoSetAllocFail(TAllocFail, TInt, TUint)

void DoSetAllocFail ( TAllocFail aType,
TInt aRate,
TUint aBurst
) [protected]

Parameters

TAllocFail aType
TInt aRate
TUint aBurst

Extension_(TUint, TAny *&, TAny *)

UIMPORT_C TInt Extension_ ( TUint aExtensionId,
TAny *& a0,
TAny * a1
) [protected, virtual]

Parameters

TUint aExtensionId
TAny *& a0
TAny * a1

FindFollowingFreeCell(SCell *, SCell *&, SCell *&)

void FindFollowingFreeCell ( SCell * aCell,
SCell *& pPrev,
SCell *& aNext
) [protected, inline]

Parameters

SCell * aCell
SCell *& pPrev
SCell *& aNext

Free(TAny *)

UIMPORT_C void Free ( TAny * aPtr ) [virtual]

Frees the specified cell and returns it to the heap.

panic
USER 42 if aCell points to an invalid cell.

Parameters

TAny * aPtr A pointer to a valid cell; this pointer can also be NULL, in which case the function does nothing and just returns.

GetAddress(const TAny *)

UIMPORT_C SCell * GetAddress ( const TAny * aCell ) const [protected]

Parameters

const TAny * aCell

Initialise()

void Initialise ( ) [protected]

IsLastCell(const SCell *)

TBool IsLastCell ( const SCell * aCell ) const [inline]

Parameters

const SCell * aCell

Lock()

void Lock ( ) const [inline]

MaxLength()

TInt MaxLength ( ) const [inline]

ReAlloc(TAny *, TInt, TInt)

UIMPORT_C TAny * ReAlloc ( TAny * aPtr,
TInt aSize,
TInt aMode = 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.

panic
USER 42, if aCell is not NULL, and does not point to a valid cell.
panic
USER 47, if the maximum unsigned value of aSize is greater than or equal to KMaxTInt/2. For example, calling ReAlloc(someptr,-1) raises this panic.
RAllocator::TReAllocMode

Parameters

TAny * aPtr A pointer to the cell to be reallocated. This may be NULL.
TInt aSize The new size of the cell. This may be bigger or smaller than the size of the original cell.
TInt aMode = 0 Flags 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.

ReAllocImpl(TAny *, TInt, TInt)

TAny * ReAllocImpl ( TAny * aPtr,
TInt aSize,
TInt aMode
) [protected, inline]

Parameters

TAny * aPtr
TInt aSize
TInt aMode

Reduce(SCell *)

TInt Reduce ( SCell * aCell ) [protected]

Parameters

SCell * aCell

Reset()

UIMPORT_C void Reset ( ) [virtual]

Frees all allocated cells on this heap.

SetBrk(TInt)

TInt SetBrk ( TInt aBrk ) [protected, inline]

Parameters

TInt aBrk

Size()

TInt Size ( ) const [inline]

Gets the current size of the heap.

This is the total number of bytes committed by the host chunk. It is the requested size rounded up by page size minus the size of RHeap object(116 bytes) minus the cell alignment overhead as shown:

Size = (Rounded committed size - Size of RHeap - Cell Alignment Overhead).

The cell alignment overhead varies between release builds and debug builds.

Note that this value is always greater than the total space available across all allocated cells.

Rheap::Available( )

TryToGrowCell(SCell *, SCell *, SCell *, TInt)

TInt TryToGrowCell ( SCell * pC,
SCell * pP,
SCell * pE,
TInt aSize
) [protected]

Parameters

SCell * pC
SCell * pP
SCell * pE
TInt aSize

TryToGrowHeap(TInt, SCell *)

TInt TryToGrowHeap ( TInt aSize,
SCell * aLastFree
) [protected]

Parameters

TInt aSize
SCell * aLastFree

Unlock()

void Unlock ( ) const [inline]

Walk(TWalkFunc, TAny *)

void Walk ( TWalkFunc aFunc,
TAny * aPtr
) [protected]

Parameters

TWalkFunc aFunc
TAny * aPtr

WalkCheckCell(TAny *, TCellType, TAny *, TInt)

void WalkCheckCell ( TAny * aPtr,
TCellType aType,
TAny * aCell,
TInt aLen
) [protected, static]

Parameters

TAny * aPtr
TCellType aType
TAny * aCell
TInt aLen

operator delete(TAny *, TAny *)

void operator delete ( TAny * aPtr,
TAny * aBase
) [inline]

Called if constructor issued by operator new(TUint aSize, TAny* aBase) throws exception. This is dummy as corresponding new operator does not allocate memory.

Parameters

TAny * aPtr
TAny * aBase

operator new(TUint, TAny *)

UIMPORT_C TAny * operator new ( TUint aSize,
TAny * aBase
)

Parameters

TUint aSize
TAny * aBase

Member Enumerations Documentation

Enum TCellType

Enumerators

EGoodAllocatedCell
EGoodFreeCell
EBadAllocatedCellSize
EBadAllocatedCellAddress
EBadFreeCellAddress
EBadFreeCellSize

Enum TDebugHeapId

Enumerators

EUser = 0

The heap is a user heap.

EKernel = 1

The heap is the Kernel heap.

Enum TDebugOp

Enumerators

EWalk = 128

Enum TDefaultShrinkRatios

Enumerators

EShrinkRatio1 = 256
EShrinkRatioDflt = 512

Member Type Definitions Documentation

Typedef TWalkFunc

typedef void(* TWalkFunc

Member Data Documentation

TInt iAlign

TInt iAlign [protected]

TInt iAllocCount

TInt iAllocCount [protected]

TUint8 * iBase

TUint8 * iBase [protected]

TInt iChunkHandle

TInt iChunkHandle [protected]

TInt iFailAllocCount

TInt iFailAllocCount [protected]

TInt iFailRate

TInt iFailRate [protected]

TAllocFail iFailType

TAllocFail iFailType [protected]

TBool iFailed

TBool iFailed [protected]

SCell iFree

SCell iFree [protected]

TInt iGrowBy

TInt iGrowBy [protected]

RFastLock iLock

RFastLock iLock [protected]

TInt iMaxLength

TInt iMaxLength [protected]

TInt iMinCell

TInt iMinCell [protected]

TInt iMinLength

TInt iMinLength [protected]

TInt iNestingLevel

TInt iNestingLevel [protected]

TInt iOffset

TInt iOffset [protected]

TInt iPageSize

TInt iPageSize [protected]

TInt iRand

TInt iRand [protected]

TAny * iTestData

TAny * iTestData [protected]

TUint8 * iTop

TUint8 * iTop [protected]