Symbian
Symbian OS Library

SYMBIAN OS V9.3

[Index] [Spacer] [Previous] [Next]



Location: e32cmn.h
Link against: euser.lib

Class RAllocator

class RAllocator : public MAllocator;

Description

Base class for heaps.

Derivation

Members

Defined in RAllocator:
AllocL(), AllocLC(), AllocZ(), AllocZL(), Check(), Close(), Count(), Count(), EAllowMoveOnShrink, ECheck, ECopyDebugInfo, ECount, EDeterministic, EFailNext, EFixedSize, EKernel, EMarkEnd, EMarkStart, EMaxHandles, ENeverMove, ENone, ERandom, EReset, ESetFail, ESingleThreaded, ETrueRandom, EUser, Extension_(), FreeZ(), Open(), RAllocator(), ReAllocL(), SCheckInfo, TAllocDebugOp, TAllocFail, TDbgHeapType, TFlags, TReAllocMode, __DbgMarkCheck(), __DbgMarkCheck(), __DbgMarkEnd(), __DbgMarkStart(), __DbgSetAllocFail(), anonymous, iAccessCount, iCellCount, iFlags, iHandleCount, iHandles, iTotalAllocSize


Construction and destruction


RAllocator()

inline RAllocator();

Description

[Top]


Member functions


Open()

IMPORT_C TInt Open();

Description

Opens this heap for shared access.

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

Return value

TInt

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


Close()

IMPORT_C void Close();

Description

Closes this shared heap.

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

Panic codes

USER

57 if the access count has already reached zero.


AllocZ()

IMPORT_C TAny *AllocZ(TInt aSize);

Description

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

TInt aSize

The size of the cell to be allocated from the current thread's heap.

Return value

TAny *

A pointer to the allocated cell. NULL, if there is insufficient memory available.

Panic codes

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.


AllocZL()

IMPORT_C TAny *AllocZL(TInt aSize);

Description

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

TInt aSize

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

Return value

TAny *

A pointer to the allocated cell.

Panic codes

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.


AllocL()

IMPORT_C TAny *AllocL(TInt aSize);

Description

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

TInt aSize

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

Return value

TAny *

A pointer to the allocated cell.

Panic codes

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.


AllocLC()

IMPORT_C TAny *AllocLC(TInt aSize);

Description

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

TInt aSize

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

Return value

TAny *

A pointer to the allocated cell.

Panic codes

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.


FreeZ()

IMPORT_C void FreeZ(TAny *&aCell);

Description

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

Parameters

TAny *&aCell

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

Panic codes

USER

42 if aCell is not NULL and does not point to a valid cell.


ReAllocL()

IMPORT_C TAny *ReAllocL(TAny *aCell, TInt aSize, TInt aMode=0);

Description

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.

Parameters

TAny *aCell

A pointer to the cell to be reallocated. This may be NULL.

TInt aSize

The new size of the cell. This may be bigger or smaller than the size of the original cell.

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

Return value

TAny *

A pointer to the reallocated cell. This may be the same as the original pointer supplied through aCell.

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.

See also:


Count()

IMPORT_C TInt Count() const;

Description

Gets the total number of cells allocated on the heap.

Return value

TInt

The number of cells allocated on the heap.


Count()

IMPORT_C TInt Count(TInt &aFreeCount) const;

Description

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

Parameters

TInt &aFreeCount

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

Return value

TInt

The number of cells allocated on the heap.


Check()

UIMPORT_C void Check() const;

Description

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

USER

47 if any corruption is found, specifically a bad allocated heap cell size.

USER

48 if any corruption is found, specifically a bad allocated heap cell address.

USER

49 if any corruption is found, specifically a bad free heap cell address.


__DbgMarkStart()

UIMPORT_C void __DbgMarkStart();

Description

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:


__DbgMarkEnd()

UIMPORT_C TUint32 __DbgMarkEnd(TInt aCount);

Description

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.

Parameters

TInt aCount

The number of allocated heap cells expected.

Return value

UIMPORT_C TUint32

A pointer to the first orphaned heap cell, if verification fails; zero otherwise.

See also:


__DbgMarkCheck()

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

Description

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

1. aaaa is the value aCount

2. bbbb is the number of allocated heap cells

3. ccc is a line number, copied from aLineNum

4. ddddd is a file name, copied from the descriptor aFileName

Note that the panic number is 1.

Parameters

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

TInt aCount

The expected number of allocated cells.

const TDesC8 &aFileName

A filename; this is displayed as part of the panic category if the check fails.

TInt aLineNum

A line number; this is displayed as part of the panic category if the check fails.

Return value

UIMPORT_C TInt

KErrNone, if successful; otherwise one of the other system wide error codes.


__DbgMarkCheck()

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

Description

Parameters

TBool aCountAll

TInt aCount

const TUint8 *aFileName

TInt aLineNum


__DbgSetAllocFail()

UIMPORT_C void __DbgSetAllocFail(TAllocFail aType, TInt aValue);

Description

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

TAllocFail aType

An enumeration which indicates how to simulate heap allocation failure.

TInt aValue

The rate of failure; when aType is RAllocator::EDeterministic, heap allocation fails every aRate attempt


Extension_()

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

Description

Parameters

TUint aExtensionId

TAny *&a0

TAny *a1

Return value

UIMPORT_C TInt

[Top]


Member structures


Struct SCheckInfo

struct SCheckInfo;

Description

Members

Defined in RAllocator::SCheckInfo:
iAll, iCount, iFileName, iLineNum

Member data


iAll

TBool iAll;

Description


iCount

TInt iCount;

Description


iFileName

const TDesC8 * iFileName;

Description


iLineNum

TInt iLineNum;

Description

[Top]


Member enumerations


Enum TAllocFail

TAllocFail

Description

A set of heap allocation failure flags.

This enumeration indicates how to simulate heap allocation failure.

See also:

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

The next attempt to allocate from this heap fails.

EReset

Cancels simulated heap allocation failure, and sets the nesting level for all allocated cells to zero.


Enum TDbgHeapType

TDbgHeapType

Description

Heap debug checking type flag.

EUser

The heap is a user heap.

EKernel

The heap is the Kernel heap.


Enum TAllocDebugOp

TAllocDebugOp

Description

ECount

EMarkStart

EMarkEnd

ECheck

ESetFail

ECopyDebugInfo


Enum TReAllocMode

TReAllocMode

Description

Flags controlling reallocation.

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.


Enum TFlags

TFlags

Description

ESingleThreaded

EFixedSize


Enum anonymous

n/a

Description

EMaxHandles

[Top]


Member data


iAccessCount

protected: TInt iAccessCount;

Description


iHandleCount

protected: TInt iHandleCount;

Description


iHandles

protected: TInt * iHandles;

Description


iFlags

protected: TUint32 iFlags;

Description


iCellCount

protected: TInt iCellCount;

Description


iTotalAllocSize

protected: TInt iTotalAllocSize;

Description