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

• MAllocator - No description.

• RAllocator - Base class for heaps.

• RHeap - Represents the default implementation for a heap.

Members

Defined in RHeap:

• Alloc(TInt)Allocates a cell of the specified size from the heap.
• AllocLen(const TAny *)constGets the length of the available space in the specified allocated cell.
• AllocSize(TInt &)constGets the number of cells allocated on this heap, and the total space allocated t...
• Available(TInt &)constGets the total free space currently available on the heap and the space availabl...
• Base()constGets a pointer to the start of the heap.
• Compress()Compresses the heap.
• EAllocCellSize
• ECellAlignment
• EFreeCellSize
• Extension_(TUint,TAny *&,TAny *)
• FindFollowingFreeCell(SCell *,SCell *&,SCell *&)
• Free(TAny *)Frees the specified cell and returns it to the heap.
• GetAddress(const TAny *)const
• MaxLength()const
• RHeap()
• ReAlloc(TAny *,TInt,TInt)Increases or decreases the size of an existing cell in the heap.
• ReAllocImpl(TAny *,TInt,TInt)
• Reset()Frees all allocated cells on this heap.
• SCellThe structure of a heap cell header for a heap cell on the free list.
• SDebugCellThe structure of a heap cell header for an allocated heap cell in a debug build....
• SetBrk(TInt)
• Size()constGets the current size of the heap.
• anonymousThe default cell alignment.
• anonymousSize of a free cell header.
• anonymousSize of an allocated cell header in a release build.
• iAlign
• iAllocCount
• iBase
• iChunkHandle
• iFailAllocCount
• iFailRate
• iFailType
• iFailed
• iFree
• iGrowBy
• iLock
• iMaxLength
• iMinCell
• iMinLength
• iNestingLevel
• iOffset
• iPageSize
• iRand
• iTestData
• iTop
• operator delete(TAny *,TAny *)Called if constructor issued by RHeap::operator new(TUint,TAny *) throws excepti...

Inherited from RAllocator:

• AllocL(TInt)Allocates a cell of specified size from the heap, and leaves if there is insuffi...
• AllocLC(TInt)Allocates a cell of specified size from the heap, and, if successful, places a p...
• AllocZ(TInt)Allocates a cell of specified size from the heap, and clears it to binary zeroes...
• AllocZL(TInt)Allocates a cell of specified size from the heap, clears it to binary zeroes, an...
• Check()constChecks the validity of the heap.
• Close()Closes this shared heap.
• Count()constGets the total number of cells allocated on the heap.
• Count(TInt &)constGets the the total number of cells allocated, and the number of free cells, on t...
• EAllowMoveOnShrinkAllows the start address of the cell to change if the cell shrinks in size.
• EBurstDeterministicaBurst allocations from this heap fail at a rate aRate. For example, if aRate is...
• EBurstFailNextaBurst allocations from this heap will fail after the next aRate - 1 allocation ...
• EBurstRandomaBurst allocations from this heap fail at a random rate; however, the interval p...
• EBurstTrueRandomaBurst allocations from this heap fail at a random rate. The interval pattern be...
• ECheck
• ECheckFailureUse this to determine how many times the current debug failure mode has failed s...
• ECopyDebugInfo
• ECount
• EDeterministicAttempts to allocate from this heap fail at a rate aRate; for example, if aRate ...
• EFailNextAn allocation from this heap will fail after the next aRate - 1 allocation attem...
• EFixedSize
• EKernelThe heap is the Kernel heap.
• EMarkEnd
• EMarkStart
• EMaxHandles
• ENeverMoveA reallocation of a cell must not change the start address of the cell.
• ENoneCancels simulated heap allocation failure.
• ERandomAttempts to allocate from this heap fail at a random rate; however, the interval...
• EResetCancels simulated heap allocation failure, and sets the nesting level for all al...
• ESetBurstFail
• ESetFail
• ESingleThreaded
• ETraceAllocs
• ETrueRandomAttempts to allocate from this heap fail at a random rate. The interval pattern ...
• EUserThe heap is a user heap.
• FreeZ(TAny *&)Frees the specified cell, returns it to the heap, and resets the pointer to NULL...
• Open()Opens this heap for shared access.
• ReAllocL(TAny *,TInt,TInt)Increases or decreases the size of an existing cell, and leaves if there is insu...
• SCheckInfo
• SRAllocatorBurstFail
• TAllocDebugOp
• TAllocFailA set of heap allocation failure flags.
• TDbgHeapTypeHeap debug checking type flag.
• TFlags
• TReAllocModeFlags controlling reallocation.
• __DbgCheckFailure()Returns the number of heap allocation failures the current debug allocator fail ...
• __DbgMarkCheck(TBool,TInt,const TDesC8 &,TInt)Checks the current number of allocated heap cells for this heap.
• __DbgMarkCheck(TBool,TInt,const TUint8 *,TInt)
• __DbgMarkEnd(TInt)Marks the end of heap cell checking at the current nested level for this heap.
• __DbgMarkStart()Marks the start of heap cell checking for this heap.
• __DbgSetAllocFail(TAllocFail,TInt)Simulates a heap allocation failure for this heap.
• __DbgSetBurstAllocFail(TAllocFail,TUint,TUint)Simulates a burst of heap allocation failures for this heap.
• iAccessCount
• iCellCount
• iFlags
• iHandleCount
• iHandles
• iTotalAllocSize

protected: inline RHeap();

Description

UIMPORT_C UIMPORT_C virtual 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

Return value

Panic codes

UIMPORT_C UIMPORT_C virtual void Free(TAny *aPtr);

Description

Frees the specified cell and returns it to the heap.

Parameters

Panic codes

UIMPORT_C UIMPORT_C virtual 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

Return value

Panic codes

See also:

• RAllocator::TReAllocModeFlags controlling reallocation.

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

Description

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

Parameters

Return value

Panic codes

UIMPORT_C UIMPORT_C virtual 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 UIMPORT_C virtual void Reset();

Description

Frees all allocated cells on this heap.

UIMPORT_C UIMPORT_C virtual TInt AllocSize(TInt &aTotalAllocSize) const;

Description

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

Parameters

Return value

UIMPORT_C UIMPORT_C virtual 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

Return value

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

Description

Parameters

Return value

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

Description

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

Parameters

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

inline TInt Size() const;

Description

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.

Return value

inline TInt MaxLength() const;

Description

Return value

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

Description

Parameters

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

Description

Parameters

Return value

protected: inline TInt SetBrk(TInt aBrk);

Description

Parameters

Return value

protected: inline TAny* ReAllocImpl(TAny *aPtr, TInt aSize, TInt aMode);

Description

Parameters

Return value

struct SCell;

Description

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

Members

Defined in RHeap::SCell:

• lenThe length of the cell, which includes the length of this header.
• nextA pointer to the next cell in the free list.

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;

Description

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

Members

Defined in RHeap::SDebugCell:

• allocCountThe cumulative number of allocated cells
• lenThe length of the cell, which includes the length of this header.
• nestingLevelThe nested level.

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

n/a

Description

The default cell alignment.

n/a

Description

Size of a free cell header.

n/a

Description

Size of an allocated cell header in a release build.

protected: TInt iMinLength;

Description

protected: TInt iMaxLength;

Description

protected: TInt iOffset;

Description

protected: TInt iGrowBy;

Description

protected: TInt iChunkHandle;

Description

protected: RFastLock iLock;

Description

protected: TUint8 * iBase;

Description

protected: TUint8 * iTop;

Description

protected: TInt iAlign;

Description

protected: TInt iMinCell;

Description

protected: TInt iPageSize;

Description

protected: SCell iFree;

Description

protected: TInt iNestingLevel;

Description

protected: TInt iAllocCount;

Description

protected: TAllocFail iFailType;

Description

protected: TInt iFailRate;

Description

protected: TBool iFailed;

Description

protected: TInt iFailAllocCount;

Description

protected: TInt iRand;

Description

protected: TAny * iTestData;

Description