Represents the default implementation for a heap. More...

#include <e32cmn.h>

Inheritance diagram for RHeap:

Classes
struct	SDebugCell
	The structure of a heap cell header for an allocated heap cell in a debug build. More...

struct	SHeapCellInfo

Public Types
enum	{ EDebugHdrSize = sizeof(SDebugCell) }
	Size of a free cell header. More...

enum	{ ECellAlignment = 8 }
	The default cell alignment. More...

enum	{ EFreeCellSize = 4 }
	Size of a free cell header. More...

enum	{ EAllocCellSize = 4 }
	Size of an allocated cell header in a release build. More...

enum	TDebugOp { EWalk = 128 , EHybridHeap }

enum	TCellType { EGoodAllocatedCell , EGoodFreeCell , EBadAllocatedCellSize , EBadAllocatedCellAddress , EBadFreeCellAddress , EBadFreeCellSize }

enum	TDebugHeapId { EUser = 0 , EKernel = 1 }

enum	TDefaultShrinkRatios { EShrinkRatio1 = 256 , EShrinkRatioDflt = 512 }

typedef void(*	TWalkFunc) (TAny , TCellType, TAny , TInt)

Public Types inherited from RAllocator
enum	TAllocFail { ERandom , ETrueRandom , EDeterministic , ENone , EFailNext , EReset , EBurstRandom , EBurstTrueRandom , EBurstDeterministic , EBurstFailNext , ECheckFailure }
	A set of heap allocation failure flags. More...

enum	TDbgHeapType { EUser , EKernel }
	Heap debug checking type flag. More...

enum	TAllocDebugOp { ECount , EMarkStart , EMarkEnd , ECheck , ESetFail , ECopyDebugInfo , ESetBurstFail , EGetFail , EGetSize =48 , EGetMaxLength , EGetBase , EAlignInteger , EAlignAddr }

enum	TReAllocMode { ENeverMove =1 , EAllowMoveOnShrink =2 }
	Flags controlling reallocation. More...

enum	TFlags { ESingleThreaded =1 , EFixedSize =2 , ETraceAllocs =4 , EMonitorMemory =8 }

enum	{ EMaxHandles =32 }

Public Member Functions
virtual UIMPORT_C TAny *	Alloc (TInt aSize)
	Allocates a cell of the specified size from the heap.

virtual UIMPORT_C void	Free (TAny *aPtr)
	Frees the specified cell and returns it to the heap.

virtual UIMPORT_C TAny *	ReAlloc (TAny *aPtr, TInt aSize, TInt aMode=0)
	Increases or decreases the size of an existing cell in the heap.

virtual UIMPORT_C TInt	AllocLen (const TAny *aCell) const
	Gets the length of the available space in the specified allocated cell.

virtual UIMPORT_C TInt	Compress ()
	Compresses the heap.

virtual UIMPORT_C void	Reset ()
	Frees all allocated cells on this heap.

virtual UIMPORT_C TInt	AllocSize (TInt &aTotalAllocSize) const
	Gets the number of cells allocated on this heap, and the total space allocated to them.

virtual UIMPORT_C TInt	Available (TInt &aBiggestBlock) const
	Gets the total free space currently available on the heap and the space available in the largest free block.

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

Public Member Functions inherited from RAllocator
	RAllocator ()

IMPORT_C TInt	Open ()
	Opens this heap for shared access.

IMPORT_C void	Close ()
	Closes this shared heap.

IMPORT_C TAny *	AllocZ (TInt aSize)
	Allocates a cell of specified size from the heap, and clears it to binary zeroes.

IMPORT_C TAny *	AllocZL (TInt aSize)
	Allocates a cell of specified size from the heap, clears it to binary zeroes, and leaves if there is insufficient memory in the heap.

IMPORT_C TAny *	AllocL (TInt aSize)
	Allocates a cell of specified size from the heap, and leaves if there is insufficient memory in the heap.

IMPORT_C TAny *	AllocLC (TInt aSize)
	Allocates a cell of specified size from the heap, and, if successful, places a pointer to the cell onto the cleanup stack.

IMPORT_C void	FreeZ (TAny *&aCell)
	Frees the specified cell, returns it to the heap, and resets the pointer to NULL.

IMPORT_C TAny *	ReAllocL (TAny *aCell, TInt aSize, TInt aMode=0)
	Increases or decreases the size of an existing cell, and leaves if there is insufficient memory in the heap.

IMPORT_C TInt	Count () const
	Gets the total number of cells allocated on the heap.

IMPORT_C TInt	Count (TInt &aFreeCount) const
	Gets the the total number of cells allocated, and the number of free cells, on the heap.

UIMPORT_C void	Check () const
	Checks the validity of the heap.

UIMPORT_C void	__DbgMarkStart ()
	Marks the start of heap cell checking for this heap.

UIMPORT_C TUint32	__DbgMarkEnd (TInt aCount)
	Marks the end of heap cell checking at the current nested level for this heap.

UIMPORT_C TInt	__DbgMarkCheck (TBool aCountAll, TInt aCount, const TDesC8 &aFileName, TInt aLineNum)
	Checks the current number of allocated heap cells for this heap.

void	__DbgMarkCheck (TBool aCountAll, TInt aCount, const TUint8 *aFileName, TInt aLineNum)

UIMPORT_C void	__DbgSetAllocFail (TAllocFail aType, TInt aRate)
	Simulates a heap allocation failure for this heap.

UIMPORT_C TAllocFail	__DbgGetAllocFail ()

UIMPORT_C void	__DbgSetBurstAllocFail (TAllocFail aType, TUint aRate, TUint aBurst)
	Simulates a burst of heap allocation failures for this heap.

UIMPORT_C TUint	__DbgCheckFailure ()
	Returns the number of heap allocation failures the current debug allocator fail function has caused so far.

UIMPORT_C TInt	Size () const

UIMPORT_C TInt	MaxLength () const

UIMPORT_C TUint8 *	Base () const

UIMPORT_C TInt	Align (TInt a) const

UIMPORT_C TAny *	Align (TAny *a) const

Protected Member Functions
virtual UIMPORT_C TInt	Extension_ (TUint aExtensionId, TAny &a0, TAny a1)

	RHeap ()

Protected Member Functions inherited from RAllocator
virtual IMPORT_C void	DoClose ()

Protected Attributes
TInt	iUnused1

TInt	iMaxLength

TInt	iUnused2

TInt	iUnused3

TInt	iChunkHandle

RFastLock	iLock

TUint8 *	iBase

TUint8 *	iTop

TInt	iAlign

TAllocFail	iFailType

TInt	iNestingLevel

TAny *	iTestData

Protected Attributes inherited from RAllocator
TInt	iAccessCount

TInt	iHandleCount

TInt *	iHandles

TUint32	iFlags

TInt	iCellCount

TInt	iTotalAllocSize

Friends
class	UserHeap

Detailed 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.

API status: Published to all clients. Released API.

Definition at line 3025 of file e32cmn.h.

Member Typedef Documentation

◆ TWalkFunc

typedef void(* RHeap::TWalkFunc) (TAny *, TCellType, TAny *, TInt)

API status: Internal component API.

Definition at line 3137 of file e32cmn.h.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Size of a free cell header.

Enumerator
EDebugHdrSize

Definition at line 3076 of file e32cmn.h.

◆ anonymous enum

anonymous enum

The default cell alignment.

Enumerator
ECellAlignment

Definition at line 3081 of file e32cmn.h.

◆ anonymous enum

anonymous enum

Size of a free cell header.

Enumerator
EFreeCellSize

Definition at line 3086 of file e32cmn.h.

◆ anonymous enum

anonymous enum

Size of an allocated cell header in a release build.

Enumerator
EAllocCellSize

Definition at line 3097 of file e32cmn.h.

◆ TCellType

enum RHeap::TCellType

API status: Internal component API.

Enumerator
EGoodAllocatedCell
EGoodFreeCell
EBadAllocatedCellSize
EBadAllocatedCellAddress
EBadFreeCellAddress
EBadFreeCellSize

Definition at line 3112 of file e32cmn.h.

◆ TDebugHeapId

enum RHeap::TDebugHeapId

API status: Internal component API.

EUser: The heap is a user heap.
EKernel: The heap is the Kernel heap.

(generated from Symbian Developer Library)

Enumerator
EUser
EKernel

Definition at line 3123 of file e32cmn.h.

◆ TDebugOp

enum RHeap::TDebugOp

API status: Internal component API.

Enumerator
EWalk
EHybridHeap

Definition at line 3105 of file e32cmn.h.

◆ TDefaultShrinkRatios

enum RHeap::TDefaultShrinkRatios

API status: Internal component API.

Enumerator
EShrinkRatio1
EShrinkRatioDflt

Definition at line 3130 of file e32cmn.h.

Constructor & Destructor Documentation

◆ RHeap()

RHeap::RHeap ( )

inlineprotected

Definition at line 3042 of file e32cmn.h.

Member Function Documentation

◆ Alloc()

UIMPORT_C TAny * RHeap::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.

Parameters

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

Panic condition: 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.

(generated from Symbian Developer Library)

Implements MAllocator.

◆ AllocLen()

UIMPORT_C TInt RHeap::AllocLen ( const TAny * aCell ) const

virtual

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

Parameters

aCell A pointer to the allocated cell.

Panic condition: USER 42 if aCell does not point to a valid cell.

(generated from Symbian Developer Library)

Implements MAllocator.

◆ AllocSize()

UIMPORT_C TInt RHeap::AllocSize ( TInt & aTotalAllocSize ) const

virtual

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

Parameters

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

(generated from Symbian Developer Library)

Implements MAllocator.

◆ Available()

UIMPORT_C TInt RHeap::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

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

(generated from Symbian Developer Library)

Implements MAllocator.

◆ Compress()

UIMPORT_C TInt RHeap::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.

(generated from Symbian Developer Library)

Implements MAllocator.

◆ DebugFunction()

virtual UIMPORT_C TInt RHeap::DebugFunction	(	TInt	aFunc,
		TAny *	a1 = `NULL`,
		TAny *	a2 = `NULL`
	)

virtual

Implements MAllocator.

◆ Extension_()

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

protectedvirtual

Reimplemented from RAllocator.

◆ Free()

UIMPORT_C void RHeap::Free ( TAny * aPtr )

virtual

Frees the specified cell and returns it to the heap.

Parameters

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

Panic condition: USER 42 if aCell points to an invalid cell.

(generated from Symbian Developer Library)

Implements MAllocator.

◆ ReAlloc()

UIMPORT_C TAny * RHeap::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:

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:

If reallocation fails, the content of the original cell is preserved.
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

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

Panic condition: USER 42, if aCell is not NULL, and does not point to a valid cell.

Panic condition: 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.

(generated from Symbian Developer Library)

Implements MAllocator.

◆ Reset()

UIMPORT_C void RHeap::Reset ( )

virtual

Frees all allocated cells on this heap.

(generated from Symbian Developer Library)

Implements MAllocator.

Friends And Related Symbol Documentation

◆ UserHeap

friend class UserHeap

friend

Definition at line 3167 of file e32cmn.h.

Member Data Documentation

◆ iAlign

TInt RHeap::iAlign

protected

Definition at line 3158 of file e32cmn.h.

◆ iBase

TUint8* RHeap::iBase

protected

Definition at line 3156 of file e32cmn.h.

◆ iChunkHandle

TInt RHeap::iChunkHandle

protected

Definition at line 3154 of file e32cmn.h.

◆ iFailType

TAllocFail RHeap::iFailType

protected

Definition at line 3163 of file e32cmn.h.

◆ iLock

RFastLock RHeap::iLock

protected

Definition at line 3155 of file e32cmn.h.

◆ iMaxLength

TInt RHeap::iMaxLength

protected

Definition at line 3150 of file e32cmn.h.

◆ iNestingLevel

TInt RHeap::iNestingLevel

protected

Definition at line 3164 of file e32cmn.h.

◆ iTestData

TAny* RHeap::iTestData

protected

Definition at line 3165 of file e32cmn.h.

◆ iTop

TUint8* RHeap::iTop

protected

Definition at line 3157 of file e32cmn.h.

◆ iUnused1

TInt RHeap::iUnused1

protected

Definition at line 3149 of file e32cmn.h.

◆ iUnused2

TInt RHeap::iUnused2

protected

Definition at line 3151 of file e32cmn.h.

◆ iUnused3

TInt RHeap::iUnused3

protected

Definition at line 3152 of file e32cmn.h.

The documentation for this class was generated from the following files:

Classes

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ TWalkFunc

Member Enumeration Documentation

◆ anonymous enum

◆ anonymous enum

◆ anonymous enum

◆ anonymous enum

◆ TCellType

◆ TDebugHeapId

◆ TDebugOp

◆ TDefaultShrinkRatios

Constructor & Destructor Documentation

◆ RHeap()

Member Function Documentation

◆ Alloc()

◆ AllocLen()

◆ AllocSize()

◆ Available()

◆ Compress()

◆ DebugFunction()

◆ Extension_()

◆ Free()

◆ ReAlloc()

◆ Reset()

Friends And Related Symbol Documentation

◆ UserHeap

Member Data Documentation

◆ iAlign

◆ iBase

◆ iChunkHandle

◆ iFailType

◆ iLock

◆ iMaxLength

◆ iNestingLevel

◆ iTestData

◆ iTop

◆ iUnused1

◆ iUnused2

◆ iUnused3