RHeap Class Reference

#include <e32cmn.h>

class RHeap : public RAllocator

Inherits from

RHeap
- RAllocator
  - MAllocator

Nested Classes and Structures

Public Member Type Definitions
typedef	void(* 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
enum	anonymous { EDebugHdrSize }
enum	anonymous { ECellAlignment }
enum	anonymous { EFreeCellSize }
enum	anonymous { EAllocCellSize }
enum	TCellType { EGoodAllocatedCell, EGoodFreeCell, EBadAllocatedCellSize, EBadAllocatedCellAddress, ..., EBadFreeCellSize }
enum	TDebugHeapId { EUser, EKernel }
enum	TDebugOp { EWalk, EHybridHeap }
enum	TDefaultShrinkRatios { EShrinkRatio1, EShrinkRatioDflt }

Public Member Functions
virtual UIMPORT_C TAny *	Alloc(TInt)
virtual UIMPORT_C TInt	AllocLen(const TAny *)
virtual UIMPORT_C TInt	AllocSize(TInt &)
virtual UIMPORT_C TInt	Available(TInt &)
virtual UIMPORT_C TInt	Compress()
virtual UIMPORT_C TInt	DebugFunction(TInt, TAny , TAny )
virtual UIMPORT_C void	Free(TAny *)
virtual UIMPORT_C TAny *	ReAlloc(TAny *, TInt, TInt)
virtual UIMPORT_C void	Reset()

Protected Member Functions
	RHeap()
virtual UIMPORT_C TInt	Extension_(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

iUnused3

TInt

iUnused3

[protected]

Member Enumeration Documentation

Enum anonymous

Size of a free cell header.

Enumerator	Value	Description
EDebugHdrSize	sizeof(SDebugCell)

Enum anonymous

The default cell alignment.

Enumerator	Value	Description
ECellAlignment	8

Enum anonymous

Size of a free cell header.

Enumerator	Value	Description
EFreeCellSize	4

Enum anonymous

Size of an allocated cell header in a release build.

Enumerator	Value	Description
EAllocCellSize	4

Enum TCellType

Enumerator	Value	Description
EGoodAllocatedCell
EGoodFreeCell
EBadAllocatedCellSize
EBadAllocatedCellAddress
EBadFreeCellAddress
EBadFreeCellSize

Enum TDebugHeapId

Enumerator	Value	Description
EUser	0	The heap is a user heap.
EKernel	1	The heap is the Kernel heap.

Enum TDebugOp

Enumerator	Value	Description
EWalk	128
EHybridHeap

Enum TDefaultShrinkRatios

Enumerator	Value	Description
EShrinkRatio1	256
EShrinkRatioDflt	512

Constructor & Destructor Documentation

RHeap ( )

RHeap

(

)

[protected, inline]

Member Function Documentation

Alloc ( TInt )

UIMPORT_C TAny *

Alloc

(

TInt

aSize

)

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

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

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.

AllocLen ( const TAny * )

UIMPORT_C TInt

AllocLen

(

const TAny *

aCell

)

const [virtual]

Reimplemented from MAllocator::AllocLen(const TAny *)const

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

Parameters
aCell	A pointer to the allocated cell.

Return Value: The length of the available space in the allocated cell.

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

AllocSize ( TInt & )

UIMPORT_C TInt

AllocSize

(

TInt &

aTotalAllocSize

)

const [virtual]

Reimplemented from MAllocator::AllocSize(TInt &)const

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.

Return Value: The number of cells allocated on this heap.

Available ( TInt & )

UIMPORT_C TInt

Available

(

TInt &

aBiggestBlock

)

const [virtual]

Reimplemented from MAllocator::Available(TInt &)const

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
aBiggestBlock	On 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 TInt

Compress

(

)

[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 TInt	DebugFunction	(	TInt	aFunc,
			TAny *	a1 = NULL,
			TAny *	a2 = NULL
		)	[virtual]

Reimplemented from MAllocator::DebugFunction(TInt,TAny *,TAny *)

Extension_ ( TUint, TAny &, TAny )

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

Reimplemented from RAllocator::Extension_(TUint,TAny *&,TAny *)

Free ( TAny * )

UIMPORT_C void

Free

(

TAny *

aPtr

)

[virtual]

Reimplemented from MAllocator::Free(TAny *)

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 Codes
USER	42 if aCell points to an invalid cell.

ReAlloc ( TAny *, TInt, TInt )

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

Reimplemented from MAllocator::ReAlloc(TAny *,TInt,TInt)

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

Reset ( )

UIMPORT_C void

Reset

(

)

[virtual]

Reimplemented from MAllocator::Reset()

Frees all allocated cells on this heap.

RHeap Class Reference

Inherits from

Nested Classes and Structures

Detailed Description

Member Type Definition Documentation

Typedef TWalkFunc

Member Attribute Documentation

iAlign

iBase

iChunkHandle

iFailType

iLock

iMaxLength

iNestingLevel

iTestData

iTop

iUnused1

iUnused2

iUnused3

Member Enumeration Documentation

Enum anonymous

Enum anonymous

Enum anonymous

Enum anonymous

Enum TCellType

Enum TDebugHeapId

Enum TDebugOp

Enum TDefaultShrinkRatios

Constructor & Destructor Documentation

RHeap ( )

Member Function Documentation

Alloc ( TInt )

AllocLen ( const TAny * )

AllocSize ( TInt & )

Available ( TInt & )

Compress ( )

DebugFunction ( TInt, TAny *, TAny * )

Extension_ ( TUint, TAny *&, TAny * )

Free ( TAny * )

ReAlloc ( TAny *, TInt, TInt )

Reset ( )

DebugFunction ( TInt, TAny , TAny )

Extension_ ( TUint, TAny &, TAny )