RAllocator Class Reference

#include <e32cmn.h>

class RAllocator : public MAllocator

Inherits from

Protected Attributes
TInt iAccessCount
TInt iCellCount
TUint32 iFlags
TInt iHandleCount
TInt *iHandles
TInt iTotalAllocSize
Public Member Enumerations
enumanonymous { EMaxHandles }
enumTAllocDebugOp { ECount, EMarkStart, EMarkEnd, ECheck, ..., EAlignAddr }
enumTAllocFail { ERandom, ETrueRandom, EDeterministic, ENone, ..., ECheckFailure }
enumTDbgHeapType { EUser, EKernel }
enumTExtension_Op { EAllocAligned }
enumTFlags { ESingleThreaded, EFixedSize, ETraceAllocs, EMonitorMemory }
enumTReAllocMode { ENeverMove, EAllowMoveOnShrink }
Public Member Functions
RAllocator()
UIMPORT_C TIntAlign(TInt)
UIMPORT_C TAny *Align(TAny *)
UIMPORT_C TAny *AllocAligned(TInt, TInt)
IMPORT_C TAny *AllocL(TInt)
IMPORT_C TAny *AllocLC(TInt)
IMPORT_C TAny *AllocZ(TInt)
IMPORT_C TAny *AllocZL(TInt)
UIMPORT_C TUint8 *Base()
UIMPORT_C voidCheck()
IMPORT_C voidClose()
IMPORT_C TIntCount()
IMPORT_C TIntCount(TInt &)
IMPORT_C voidFreeZ(TAny *&)
UIMPORT_C TIntMaxLength()
IMPORT_C TIntOpen()
IMPORT_C TAny *ReAllocL(TAny *, TInt, TInt)
UIMPORT_C TIntSize()
UIMPORT_C TUint__DbgCheckFailure()
UIMPORT_C TAllocFail__DbgGetAllocFail()
UIMPORT_C TInt__DbgMarkCheck(TBool, TInt, const TDesC8 &, TInt)
void__DbgMarkCheck(TBool, TInt, const TUint8 *, TInt)
UIMPORT_C TUint32__DbgMarkEnd(TInt)
UIMPORT_C void__DbgMarkStart()
UIMPORT_C void__DbgSetAllocFail(TAllocFail, TInt)
UIMPORT_C void__DbgSetBurstAllocFail(TAllocFail, TUint, TUint)
Protected Member Functions
virtual IMPORT_C voidDoClose()
virtual UIMPORT_C TIntExtension_(TUint, TAny *&, TAny *)
Inherited Functions
MAllocator::Alloc(TInt)
MAllocator::AllocLen(const TAny *)const
MAllocator::AllocSize(TInt &)const
MAllocator::Available(TInt &)const
MAllocator::Compress()
MAllocator::DebugFunction(TInt,TAny *,TAny *)
MAllocator::Free(TAny *)
MAllocator::ReAlloc(TAny *,TInt,TInt)
MAllocator::Reset()

Detailed Description

Base class for heaps.

Member Attribute Documentation

iAccessCount

TInt iAccessCount[protected]

iCellCount

TInt iCellCount[protected]

iFlags

TUint32 iFlags[protected]

iHandleCount

TInt iHandleCount[protected]

iHandles

TInt *iHandles[protected]

iTotalAllocSize

TInt iTotalAllocSize[protected]

Member Enumeration Documentation

Enum anonymous

EnumeratorValueDescription
EMaxHandles32

Enum TAllocDebugOp

Enum TAllocFail

A set of heap allocation failure flags.

This enumeration indicates how to simulate heap allocation failure.

See also: RAllocator::__DbgSetAllocFail()

EnumeratorValueDescription
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()

Enum TDbgHeapType

Heap debug checking type flag.

EnumeratorValueDescription
EUser

The heap is a user heap.

EKernel

The heap is the Kernel heap.

Enum TExtension_Op

EnumeratorValueDescription
EAllocAligned

Enum TFlags

EnumeratorValueDescription
ESingleThreaded1
EFixedSize2
ETraceAllocs4
EMonitorMemory8

Enum TReAllocMode

Flags controlling reallocation.

EnumeratorValueDescription
ENeverMove1

A reallocation of a cell must not change the start address of the cell.

EAllowMoveOnShrink2

Allows the start address of the cell to change if the cell shrinks in size.

Constructor & Destructor Documentation

RAllocator ( )

RAllocator()[inline]

Member Function Documentation

Align ( TInt )

UIMPORT_C TIntAlign(TInta)const

Align ( TAny * )

UIMPORT_C TAny *Align(TAny *a)const

AllocAligned ( TInt, TInt )

UIMPORT_C TAny *AllocAligned(TIntaAlignment,
TIntaSize
)

Allocates a cell with specified size from heap which is aligned in accord with the alignment argument. The alignment argument should be a power of two. If the argument is not a power of two, the nearest greater power is used.

See also: KMaxTInt

Parameters
aAlignmentAlignment value or allocated cell
aSizeThe size of the cell to be allocated from the heap
Return Value
A pointer to the allocated cell. NULL if there is insufficient memory available or the current allocator does not support aligned allocation.
Panic Codes
USER47 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.

AllocL ( TInt )

IMPORT_C TAny *AllocL(TIntaSize)

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
aSizeThe size of the cell to be allocated from the heap.
Return Value
A pointer to the allocated cell.
Panic Codes
USER47 if the maximum unsigned value of aSize is greater than or equal to KMaxTInt/2. For example, calling Alloc(-1) raises this panic.

AllocLC ( TInt )

IMPORT_C TAny *AllocLC(TIntaSize)

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
aSizeThe size of the cell to be allocated from the heap.
Return Value
A pointer to the allocated cell.
Panic Codes
USER47 if the maximum unsigned value of aSize is greater than or equal to KMaxTInt/2. For example, calling Alloc(-1) raises this panic.

AllocZ ( TInt )

IMPORT_C TAny *AllocZ(TIntaSize)

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
aSizeThe size of the cell to be allocated from the current thread's heap.
Return Value
A pointer to the allocated cell. NULL, if there is insufficient memory available.
Panic Codes
USER47 if the maximum unsigned value of aSize is greater than or equal to KMaxTInt/2. For example, calling Alloc(-1) raises this panic.

AllocZL ( TInt )

IMPORT_C TAny *AllocZL(TIntaSize)

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
aSizeThe size of the cell to be allocated from the heap.
Return Value
A pointer to the allocated cell.
Panic Codes
USER47 if the maximum unsigned value of aSize is greater than or equal to KMaxTInt/2. For example, calling Alloc(-1) raises this panic.

Base ( )

UIMPORT_C TUint8 *Base()const

Gets a pointer to the start of the heap.

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 address of the start of the heap, as it is not as meaningful as it was in older heap implementations. In fact, the "base" might not even be the base of the heap at all!

In other words, you can call this but it's not guaranteed to point to the start of the heap (and in fact it never really was, even in legacy implementations).

Return Value
A pointer to the base of the heap. Maybe.

Check ( )

UIMPORT_C voidCheck()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 Codes
USER47 if any corruption is found, specifically a bad allocated heap cell size.
USER48 if any corruption is found, specifically a bad allocated heap cell address.
USER49 if any corruption is found, specifically a bad free heap cell address.

Close ( )

IMPORT_C voidClose()

Closes this shared heap.

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

Panic Codes
USER57 if the access count has already reached zero.

Count ( )

IMPORT_C TIntCount()const

Gets the total number of cells allocated on the heap.

Return Value
The number of cells allocated on the heap.

Count ( TInt & )

IMPORT_C TIntCount(TInt &aFreeCount)const

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

Parameters
aFreeCountOn return, contains the number of free cells on the heap.
Return Value
The number of cells allocated on the heap.

DoClose ( )

IMPORT_C voidDoClose()[protected, virtual]

Extension_ ( TUint, TAny *&, TAny * )

UIMPORT_C TIntExtension_(TUintaExtensionId,
TAny *&a0,
TAny *a1
)[protected, virtual]

FreeZ ( TAny *& )

IMPORT_C voidFreeZ(TAny *&aCell)

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

Parameters
aCellA reference to a pointer to a valid cell to be freed. If NULL this function call will be ignored.
Panic Codes
USER42 if aCell is not NULL and does not point to a valid cell.

MaxLength ( )

UIMPORT_C TIntMaxLength()const

Return Value
The maximum length to which the heap can grow.

Open ( )

IMPORT_C TIntOpen()

Opens this heap for shared access.

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

Return Value
KErrNone if successful; KErrGeneral, if the original valeu of the access count was not positive.

ReAllocL ( TAny *, TInt, TInt )

IMPORT_C TAny *ReAllocL(TAny *aCell,
TIntaSize,
TIntaMode = 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:

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

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.

See also: RAllocator::TReAllocMode

Parameters
aCellA pointer to the cell to be reallocated. This may be NULL.
aSizeThe new size of the cell. This may be bigger or smaller than the size of the original cell.
aModeFlags 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
A pointer to the reallocated cell. This may be the same as the original pointer supplied through aCell.
Panic Codes
USER42, if aCell is not NULL, and does not point to a valid cell.
USER47, if the maximum unsigned value of aSize is greater than or equal to KMaxTInt/2. For example, calling ReAlloc(someptr,-1) raises this panic.

Size ( )

UIMPORT_C TIntSize()const

Gets the current size of the heap.

This is the total number of bytes committed by the host chunk, less the number of bytes used by the heap's metadata (the internal structures used for keeping track of allocated and free memory).

Size = (Rounded committed size - size of heap metadata).

Return Value
The size of the heap, in bytes.

__DbgCheckFailure ( )

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

See also: RAllocator::TAllocFail

Return Value
The number of heap allocation failures the current debug fail function has caused.

__DbgGetAllocFail ( )

UIMPORT_C TAllocFail__DbgGetAllocFail()

Obtains the current heap failure simulation type.

After calling __DbgSetAllocFail(), this function may be called to retrieve the value set. This is useful primarily for test code that doesn't know if a heap has been set to fail and needs to check.

Return Value
RAllocator::ENone if heap is not in failure simulation mode; Otherwise one of the other RAllocator::TAllocFail enumerations

__DbgMarkCheck ( TBool, TInt, const TDesC8 &, TInt )

UIMPORT_C TInt__DbgMarkCheck(TBoolaCountAll,
TIntaCount,
const TDesC8 &aFileName,
TIntaLineNum
)

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, which takes the form:

ALLOC: aaaabbbb

Where aaaa is the value aCount and bbbb is the number of allocated heap cells. Both values are in hexadecimal format. The panic number is 1.

Parameters
aCountAllIf 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.
aCountThe expected number of allocated cells.
aFileNameA filename; this is not used
aLineNumA line number; this is not used
Return Value
KErrNone, if successful; otherwise one of the other system wide error codes.

__DbgMarkCheck ( TBool, TInt, const TUint8 *, TInt )

void__DbgMarkCheck(TBoolaCountAll,
TIntaCount,
const TUint8 *aFileName,
TIntaLineNum
)[inline]

__DbgMarkEnd ( TInt )

UIMPORT_C TUint32__DbgMarkEnd(TIntaCount)

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

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.

See also: RAllocator::__DbgMarkStart()

Parameters
aCountThe number of allocated heap cells expected.
Return Value
A pointer to the first orphaned heap cell, if verification fails; zero otherwise.

__DbgMarkStart ( )

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

See also: RAllocator::__DbgMarkEnd()

__DbgSetAllocFail ( TAllocFail, TInt )

UIMPORT_C void__DbgSetAllocFail(TAllocFailaType,
TIntaRate
)

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:

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

2. For failure types RAllocator::EFailNext and RAllocator::ENone, set aRate to 1.

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

__DbgSetBurstAllocFail ( TAllocFail, TUint, TUint )

UIMPORT_C void__DbgSetBurstAllocFail(TAllocFailaType,
TUintaRate,
TUintaBurst
)

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:

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

2. For failure types RAllocator::EFailNext and RAllocator::ENone, set aRate to 1.

See also: RAllocator::TAllocFail

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