Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Location: e32cmn.h
Link against: euser.lib

Class RHeap

class RHeap : public RAllocator;

Description

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.

Derivation

Members

Defined in RHeap:
Alloc(), AllocLen(), AllocSize(), Available(), Base(), Compress(), EAllocCellSize, ECellAlignment, EFreeCellSize, Extension_(), FindFollowingFreeCell(), Free(), GetAddress(), RHeap(), ReAlloc(), Reset(), SCell, SDebugCell, SetBrk(), Size(), anonymous, anonymous, anonymous, iAlign, iAllocCount, iBase, iChunkHandle, iFailAllocCount, iFailRate, iFailType, iFailed, iFree, iGrowBy, iLock, iMaxLength, iMinCell, iMinLength, iNestingLevel, iOffset, iPageSize, iRand, iTestData, iTop, operator delete()

Inherited from RAllocator:
AllocL(), AllocLC(), AllocZ(), AllocZL(), Check(), Close(), Count(), EAllowMoveOnShrink, ECheck, ECopyDebugInfo, ECount, EDeterministic, EFailNext, EFixedSize, EKernel, EMarkEnd, EMarkStart, EMaxHandles, ENeverMove, ENone, ERandom, EReset, ESetFail, ESingleThreaded, ETrueRandom, EUser, FreeZ(), Open(), ReAllocL(), SCheckInfo, TAllocDebugOp, TAllocFail, TDbgHeapType, TFlags, TReAllocMode, __DbgMarkCheck(), __DbgMarkEnd(), __DbgMarkStart(), __DbgSetAllocFail(), iAccessCount, iCellCount, iFlags, iHandleCount, iHandles, iTotalAllocSize


Construction and destruction


RHeap()

protected: inline RHeap();

Description

[Top]


Member functions


Alloc()

virtual UIMPORT_C TAny *Alloc(TInt aSize);

Description

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.

Parameters

TInt aSize

The size of the cell to be allocated from the heap

Return value

UIMPORT_C TAny *

A pointer to the allocated cell. NULL if there is insufficient memory available.

Panic codes

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.

See also:


Free()

virtual UIMPORT_C void Free(TAny *aPtr);

Description

Frees the specified cell and returns it to the heap.

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.

Panic codes

USER

42 if aCell points to an invalid cell.


ReAlloc()

virtual UIMPORT_C TAny *ReAlloc(TAny *aPtr, TInt aSize, TInt aMode=0);

Description

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.

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

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.

Return value

UIMPORT_C TAny *

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

USER

42, if aCell is not NULL, and does not point to a valid cell.

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.

See also:


AllocLen()

virtual UIMPORT_C TInt AllocLen(const TAny *aCell) const;

Description

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

Parameters

const TAny *aCell

A pointer to the allocated cell.

Return value

UIMPORT_C TInt

The length of the available space in the allocated cell.

Panic codes

USER

42 if aCell does not point to a valid cell.


Compress()

virtual UIMPORT_C TInt Compress();

Description

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

UIMPORT_C TInt

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


Reset()

virtual UIMPORT_C void Reset();

Description

Frees all allocated cells on this heap.


AllocSize()

virtual UIMPORT_C TInt AllocSize(TInt &aTotalAllocSize) const;

Description

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.

Return value

UIMPORT_C TInt

The number of cells allocated on this heap.


Available()

virtual UIMPORT_C TInt Available(TInt &aBiggestBlock) const;

Description

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.

Return value

UIMPORT_C TInt

The total free space currently available on the heap.


Extension_()

protected: virtual UIMPORT_C TInt Extension_(TUint aExtensionId, TAny *&a0, TAny *a1);

Description

Parameters

TUint aExtensionId

TAny *&a0

TAny *a1

Return value

UIMPORT_C TInt


operator delete()

inline void operator delete(TAny *aPtr, TAny *aBase);

Description

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


Base()

inline TUint8 *Base() const;

Description

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.

Return value

TUint8 *

A pointer to the base of the heap.


Size()

inline TInt Size() const;

Description

Gets the current size of the heap.

This is the total number of bytes committed by the host chunk.

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

Return value

TInt

The size of the heap.


FindFollowingFreeCell()

protected: inline void FindFollowingFreeCell(SCell *aCell, SCell *&pPrev, SCell *&aNext);

Description

Parameters

SCell *aCell

SCell *&pPrev

SCell *&aNext


GetAddress()

protected: UIMPORT_C SCell *GetAddress(const TAny *aCell) const;

Description

Parameters

const TAny *aCell

Return value

UIMPORT_C SCell *


SetBrk()

protected: inline TInt SetBrk(TInt aBrk);

Description

Parameters

TInt aBrk

Return value

TInt

[Top]


Member structures


Struct SCell

struct SCell;

Description

The structure of a heap cell header for a heap cell on the free list.

Members

Defined in RHeap::SCell:
len, next

Member data


len

TInt len;

Description

The length of the cell, which includes the length of this header.


next

SCell * next;

Description

A pointer to the next cell in the free list.


Struct SDebugCell

struct SDebugCell;

Description

The structure of a heap cell header for an allocated heap cell in a debug build.

Members

Defined in RHeap::SDebugCell:
allocCount, len, nestingLevel

Member data


len

TInt len;

Description

The length of the cell, which includes the length of this header.


nestingLevel

TInt nestingLevel;

Description

The nested level.


allocCount

TInt allocCount;

Description

The cumulative number of allocated cells

[Top]


Member enumerations


Enum anonymous

n/a

Description

The default cell alignment.

ECellAlignment


Enum anonymous

n/a

Description

Size of a free cell header.

EFreeCellSize


Enum anonymous

n/a

Description

Size of an allocated cell header in a release build.

EAllocCellSize

[Top]


Member data


iMinLength

protected: TInt iMinLength;

Description


iMaxLength

protected: TInt iMaxLength;

Description


iOffset

protected: TInt iOffset;

Description


iGrowBy

protected: TInt iGrowBy;

Description


iChunkHandle

protected: TInt iChunkHandle;

Description


iLock

protected: RFastLock iLock;

Description


iBase

protected: TUint8 * iBase;

Description


iTop

protected: TUint8 * iTop;

Description


iAlign

protected: TInt iAlign;

Description


iMinCell

protected: TInt iMinCell;

Description


iPageSize

protected: TInt iPageSize;

Description


iFree

protected: SCell iFree;

Description


iNestingLevel

protected: TInt iNestingLevel;

Description


iAllocCount

protected: TInt iAllocCount;

Description


iFailType

protected: TAllocFail iFailType;

Description


iFailRate

protected: TInt iFailRate;

Description


iFailed

protected: TBool iFailed;

Description


iFailAllocCount

protected: TInt iFailAllocCount;

Description


iRand

protected: TInt iRand;

Description


iTestData

protected: TAny * iTestData;

Description