Base class for heaps. More...

#include <e32cmn.h>

Inheritance diagram for RAllocator:

Classes
struct	SCheckInfo

struct	SRAllocatorBurstFail

Public Types
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
	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

Public Member Functions inherited from MAllocator
virtual TAny *	Alloc (TInt aSize)=0

virtual void	Free (TAny *aPtr)=0

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

virtual TInt	AllocLen (const TAny *aCell) const =0

virtual TInt	Compress ()=0

virtual void	Reset ()=0

virtual TInt	AllocSize (TInt &aTotalAllocSize) const =0

virtual TInt	Available (TInt &aBiggestBlock) const =0

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

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

virtual IMPORT_C void	DoClose ()

Protected Attributes
TInt	iAccessCount

TInt	iHandleCount

TInt *	iHandles

TUint32	iFlags

TInt	iCellCount

TInt	iTotalAllocSize

Detailed Description

Base class for heaps.

API status: Published to all clients. Released API.

Definition at line 2820 of file e32cmn.h.

Member Enumeration Documentation

◆ anonymous enum

anonymous enum

Enumerator
EMaxHandles

Definition at line 2952 of file e32cmn.h.

◆ TAllocDebugOp

enum RAllocator::TAllocDebugOp

Enumerator
ECount
EMarkStart
EMarkEnd
ECheck
ESetFail
ECopyDebugInfo
ESetBurstFail
EGetFail
EGetSize
EGetMaxLength
EGetBase
EAlignInteger
EAlignAddr

Definition at line 2923 of file e32cmn.h.

◆ TAllocFail

enum RAllocator::TAllocFail

A set of heap allocation failure flags.

This enumeration indicates how to simulate heap allocation failure.

See also: RAllocator::__DbgSetAllocFail()

Enumerator
ERandom	Attempts to allocate from this heap fail at a random rate; however, the interval pattern between failures is the same every time simulation is started.
ETrueRandom	Attempts to allocate from this heap fail at a random rate. The interval pattern between failures may be different every time the simulation is started.
EDeterministic	Attempts to allocate from this heap fail at a rate aRate; for example, if aRate is 3, allocation fails at every third attempt.
ENone	Cancels simulated heap allocation failure.
EFailNext	An allocation from this heap will fail after the next aRate - 1 allocation attempts. For example, if aRate = 1 then the next attempt to allocate from this heap will fail.
EReset	Cancels simulated heap allocation failure, and sets the nesting level for all allocated cells to zero.
EBurstRandom	aBurst allocations from this heap fail at a random rate; however, the interval pattern between failures is the same every time the simulation is started.
EBurstTrueRandom	aBurst allocations from this heap fail at a random rate. The interval pattern between failures may be different every time the simulation is started.
EBurstDeterministic	aBurst allocations from this heap fail at a rate aRate. For example, if aRate is 10 and aBurst is 2, then 2 allocations will fail at every tenth attempt.
EBurstFailNext	aBurst allocations from this heap will fail after the next aRate - 1 allocation attempts have occurred. For example, if aRate = 1 and aBurst = 3 then the next 3 attempts to allocate from this heap will fail.
ECheckFailure	Use this to determine how many times the current debug failure mode has failed so far. See also RAllocator::__DbgCheckFailure()

Definition at line 2830 of file e32cmn.h.

◆ TDbgHeapType

enum RAllocator::TDbgHeapType

Heap debug checking type flag.

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

Definition at line 2910 of file e32cmn.h.

◆ TFlags

enum RAllocator::TFlags

Enumerator
ESingleThreaded
EFixedSize
ETraceAllocs
EMonitorMemory

Definition at line 2947 of file e32cmn.h.

◆ TReAllocMode

enum RAllocator::TReAllocMode

Flags controlling reallocation.

Enumerator
ENeverMove	A reallocation of a cell must not change the start address of the cell.
EAllowMoveOnShrink	Allows the start address of the cell to change if the cell shrinks in size.

Definition at line 2932 of file e32cmn.h.

Constructor & Destructor Documentation

◆ RAllocator()

RAllocator::RAllocator ( )

inline

Member Function Documentation

◆ __DbgCheckFailure()

UIMPORT_C TUint RAllocator::__DbgCheckFailure ( )

Returns the number of heap allocation failures the current debug allocator fail function has caused so far.

This is intended to only be used with fail types RAllocator::EFailNext, RAllocator::EBurstFailNext, RAllocator::EDeterministic and RAllocator::EBurstDeterministic. The return value is unreliable for all other fail types.

RAllocator::TAllocFail

(generated from Symbian Developer Library)

◆ __DbgGetAllocFail()

UIMPORT_C TAllocFail RAllocator::__DbgGetAllocFail ( )

◆ __DbgMarkCheck() [1/2]

UIMPORT_C TInt RAllocator::__DbgMarkCheck	(	TBool	aCountAll,
		TInt	aCount,
		const TDesC8 &	aFileName,
		TInt	aLineNum
	)

Checks the current number of allocated heap cells for this heap.

If aCountAll is true, the function checks that the total number of allocated cells on this heap is the same as aCount. If aCountAll is false, then the function checks that the number of allocated cells at the current nested level is the same as aCount.

If checking fails, the function raises a panic; information about the failure is put into the panic category; this takes the form:

ALLOC COUNT\rExpected aaa\rAllocated bbb\rLn: ccc ddddd

where

aaaa is the value aCount
bbbb is the number of allocated heap cells
ccc is a line number, copied from aLineNum
ddddd is a file name, copied from the descriptor aFileName

Note that the panic number is 1.

Parameters

aCountAll	If true, the function checks that the total number of allocated cells on this heap is the same as aCount. If false, the function checks that the number of allocated cells at the current nested level is the same as aCount.
aCount	The expected number of allocated cells.
aFileName	A filename; this is displayed as part of the panic category if the check fails.
aLineNum	A line number; this is displayed as part of the panic category if the check fails.

(generated from Symbian Developer Library)

◆ __DbgMarkCheck() [2/2]

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

inline

◆ __DbgMarkEnd()

UIMPORT_C TUint32 RAllocator::__DbgMarkEnd ( TInt aCount )

Marks the end of heap cell checking at the current nested level for this heap.

A call to this function should match an earlier call to __DbgMarkStart(). If there are more calls to this function than calls to __DbgMarkStart(), then this function raises a USER 51 panic.

The function checks that the number of heap cells allocated, at the current nested level, is aCount. The most common value for aCount is zero, reflecting the fact that most developers check that all memory allocated since a previous call to __DbgMarkStart() has been freed.

If the check fails, the function returns a pointer to the first orphaned heap cell.

RAllocator::__DbgMarkStart()

Parameters

aCount The number of allocated heap cells expected.

(generated from Symbian Developer Library)

◆ __DbgMarkStart()

UIMPORT_C void RAllocator::__DbgMarkStart ( )

Marks the start of heap cell checking for this heap.

If earlier calls to __DbgMarkStart() have been made, then this call to __DbgMarkStart() marks the start of a new nested level of heap cell checking.

Every call to __DbgMarkStart() should be matched by a later call to __DbgMarkEnd() to verify that the number of heap cells allocated, at the current nested level, is as expected. This expected number of heap cells is passed to __DbgMarkEnd() as a parameter; however, the most common expected number is zero, reflecting the fact that most developers check that all memory allocated since a previous call to __DbgMarkStart() has been freed.

RAllocator::__DbgMarkEnd()

(generated from Symbian Developer Library)

◆ __DbgSetAllocFail()

UIMPORT_C void RAllocator::__DbgSetAllocFail	(	TAllocFail	aType,
		TInt	aRate
	)

Simulates a heap allocation failure for this heap.

The failure occurs on subsequent calls to new or any of the functions which allocate memory from this heap.

The timing of the allocation failure depends on the type of allocation failure requested, i.e. on the value of aType.

The simulation of heap allocation failure is cancelled if aType is given the value RAllocator::ENone.

Notes:

If the failure type is RAllocator::EFailNext, the next attempt to allocate from this heap fails; however, no further failures will occur.
For failure types RAllocator::EFailNext and RAllocator::ENone, set aRate to 1.

Parameters

aType	An enumeration which indicates how to simulate heap allocation failure.
aRate	The rate of failure; when aType is RAllocator::EDeterministic, heap allocation fails every aRate attempts

(generated from Symbian Developer Library)

◆ __DbgSetBurstAllocFail()

UIMPORT_C void RAllocator::__DbgSetBurstAllocFail	(	TAllocFail	aType,
		TUint	aRate,
		TUint	aBurst
	)

Simulates a burst of heap allocation failures for this heap.

The failure occurs for aBurst allocations attempt via subsequent calls to new or any of the functions which allocate memory from this heap.

The timing of the allocation failure depends on the type of allocation failure requested, i.e. on the value of aType.

The simulation of heap allocation failure is cancelled if aType is given the value RAllocator::ENone.

Notes:

If the failure type is RAllocator::EFailNext or RAllocator::EBurstFailNext, the next one or aBurst attempts to allocate from this heap will fail; however, no further failures will occur.
For failure types RAllocator::EFailNext and RAllocator::ENone, set aRate to 1.

RAllocator::TAllocFail

Parameters

aType	An enumeration which indicates how to simulate heap allocation failure.
aRate	The rate of failure; when aType is RAllocator::EDeterministic, heap allocation fails every aRate attempts.
aBurst	The number of consecutive heap allocations that will fail each time the allocations should fail.

(generated from Symbian Developer Library)

◆ Align() [1/2]

UIMPORT_C TAny * RAllocator::Align ( TAny * a ) const

◆ Align() [2/2]

UIMPORT_C TInt RAllocator::Align ( TInt a ) const

◆ AllocL()

IMPORT_C TAny * RAllocator::AllocL ( TInt aSize )

Allocates a cell of specified size from the heap, and leaves if there is insufficient memory in the heap.

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 KMaxTInt/2. For example, calling Alloc(-1) raises this panic.

(generated from Symbian Developer Library)

◆ AllocLC()

IMPORT_C TAny * RAllocator::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.

The function leaves if there is insufficient memory in the heap.

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 KMaxTInt/2. For example, calling Alloc(-1) raises this panic.

(generated from Symbian Developer Library)

◆ AllocZ()

IMPORT_C TAny * RAllocator::AllocZ ( TInt aSize )

Allocates a cell of specified size from the heap, and clears it to binary zeroes.

If there is insufficient memory available on the heap from which to allocate a cell of the required size, the function returns NULL.

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 current thread's heap.

Panic condition: USER 47 if the maximum unsigned value of aSize is greater than or equal to KMaxTInt/2. For example, calling Alloc(-1) raises this panic.

(generated from Symbian Developer Library)

◆ AllocZL()

IMPORT_C TAny * RAllocator::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.

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 KMaxTInt/2. For example, calling Alloc(-1) raises this panic.

(generated from Symbian Developer Library)

◆ Base()

UIMPORT_C TUint8 * RAllocator::Base ( ) const

◆ Check()

UIMPORT_C void RAllocator::Check ( ) const

Checks the validity of the heap.

The function walks through the list of allocated cells and the list of free cells checking that this heap is consistent and complete.

Panic condition: USER 47 if any corruption is found, specifically a bad allocated heap cell size.

Panic condition: USER 48 if any corruption is found, specifically a bad allocated heap cell address.

Panic condition: USER 49 if any corruption is found, specifically a bad free heap cell address.

(generated from Symbian Developer Library)

◆ Close()

IMPORT_C void RAllocator::Close ( )

Closes this shared heap.

Closing the heap decreases the heap's access count by one.

Panic condition: USER 57 if the access count has already reached zero.

(generated from Symbian Developer Library)

◆ Count() [1/2]

IMPORT_C TInt RAllocator::Count ( ) const

Gets the total number of cells allocated on the heap.

(generated from Symbian Developer Library)

◆ Count() [2/2]

IMPORT_C TInt RAllocator::Count ( TInt & aFreeCount ) const

Gets the the total number of cells allocated, and the number of free cells, on the heap.

Parameters

aFreeCount On return, contains the number of free cells on the heap.

(generated from Symbian Developer Library)

◆ DoClose()

virtual IMPORT_C void RAllocator::DoClose ( )

protectedvirtual

◆ Extension_()

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

protectedvirtual

Implements MAllocator.

Reimplemented in RHeap.

◆ FreeZ()

IMPORT_C void RAllocator::FreeZ ( TAny *& aCell )

Frees the specified cell, returns it to the heap, and resets the pointer to NULL.

Parameters

aCell A reference to a pointer to a valid cell to be freed. If NULL this function call will be ignored.

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

(generated from Symbian Developer Library)

◆ MaxLength()

UIMPORT_C TInt RAllocator::MaxLength ( ) const

◆ Open()

IMPORT_C TInt RAllocator::Open ( )

Opens this heap for shared access.

Opening the heap increases the heap's access count by one.

(generated from Symbian Developer Library)

◆ ReAllocL()

IMPORT_C TAny * RAllocator::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.

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

Note that in debug mode, the function leaves 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.

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

aCell	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)

◆ Size()

UIMPORT_C TInt RAllocator::Size ( ) const

Member Data Documentation

◆ iAccessCount

TInt RAllocator::iAccessCount

protected

Definition at line 2990 of file e32cmn.h.

◆ iCellCount

TInt RAllocator::iCellCount

protected

Definition at line 2994 of file e32cmn.h.

◆ iFlags

TUint32 RAllocator::iFlags

protected

Definition at line 2993 of file e32cmn.h.

◆ iHandleCount

TInt RAllocator::iHandleCount

protected

Definition at line 2991 of file e32cmn.h.

◆ iHandles

TInt* RAllocator::iHandles

protected

Definition at line 2992 of file e32cmn.h.

◆ iTotalAllocSize

TInt RAllocator::iTotalAllocSize

protected

Definition at line 2995 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

Detailed Description

Member Enumeration Documentation

◆ anonymous enum

◆ TAllocDebugOp

◆ TAllocFail

◆ TDbgHeapType

◆ TFlags

◆ TReAllocMode

Constructor & Destructor Documentation

◆ RAllocator()

Member Function Documentation

◆ __DbgCheckFailure()

◆ __DbgGetAllocFail()

◆ __DbgMarkCheck() [1/2]

◆ __DbgMarkCheck() [2/2]

◆ __DbgMarkEnd()

◆ __DbgMarkStart()

◆ __DbgSetAllocFail()

◆ __DbgSetBurstAllocFail()

◆ Align() [1/2]

◆ Align() [2/2]

◆ AllocL()

◆ AllocLC()

◆ AllocZ()

◆ AllocZL()

◆ Base()

◆ Check()

◆ Close()

◆ Count() [1/2]

◆ Count() [2/2]

◆ DoClose()

◆ Extension_()

◆ FreeZ()

◆ MaxLength()

◆ Open()

◆ ReAllocL()

◆ Size()

Member Data Documentation

◆ iAccessCount

◆ iCellCount

◆ iFlags

◆ iHandleCount

◆ iHandles

◆ iTotalAllocSize