Class RHeap

RHeap

Support

Supported from 5.0

Description

Represents a heap.

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.

Derivation

RHeap Represents a heap RHeapBase Base class for RHeap, which encapsulates a heap

Defined in RHeap:
Adjust(), AdjustL(), Alloc(), AllocL(), AllocLC(), AllocLen(), AllocSize(), Available(), Base(), Check(), Close(), Compress(), Count(), EDeterministic, EFailNext, EKernel, ENone, ERandom, ETrueRandom, EUser, Free(), FreeAll(), FreeZ(), Open(), ReAlloc(), ReAllocL(), Size(), TAllocFail, TAllocSize, TDbgHeapType, Type(), __DbgMarkCheck(), __DbgMarkEnd(), __DbgMarkStart(), __DbgSetAllocFail()

Inherited from RHeapBase:
EChunkNormal, EChunkStack, EChunkSupervisor, EFixedAddress, THeapType

TInt Open();

Description

Opens this heap for shared access. Opening the heap increases the heap's access count by one.

The heap must be of type EChunkNormal otherwise the function raises a USER 58 panic.

Return value

TInt KErrNone if successful, otherwise another of the system-wide error codes.

void Close();

Description

Closes this shared heap. Closing the heap decreases the heap's access count by one. If the access reaches zero, the hosting chunk is closed.

Notes:

• The heap must be of type EChunkNormal otherwise the function is not honoured and the close is not performed.

• Trying to close the heap if the access count is already zero, raises a USER 57 panic.

TAny* Alloc(TInt aSize);

Description

Allocates a cell of a 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.

Notes:

• The maximum unsigned value of aSize must be less than the value of KMaxTInt/2. Passing an unsigned value greater than or equal to KMaxTInt/2 causes the functions to raise a USER 47 panic. For example, calling Alloc(-1) raises a panic.

• 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. NULL if there is insufficient memory available.

TAny* AllocL(TInt aSize);

Description

Allocates a cell of a 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 leaves.

Notes:

• The maximum unsigned value of aSize must be less than the value of KMaxTInt/2. Passing an unsigned value greater than or equal to KMaxTInt/2 causes the functions to raise a USER 47 panic. For example, calling AllocL(-1) causes a panic.

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

TAny* AllocLC(TInt aSize);

Description

Allocates a cell of a specified size from the heap and, if successful, places a pointer to the cell onto the cleanup stack.

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

Notes:

• The maximum unsigned value of aSize must be less than the value of KMaxTInt/2. Passing an unsigned value greater than or equal to KMaxTInt/2 causes the functions to raise a USER 47 panic. For example, calling AllocLC(-1) causes a panic.

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

TAny* ReAlloc(TAny* aCell,TInt aSize);

Description

Increases or decreases the size of the existing cell to the new value. If there is insufficient memory available in the heap from which to reallocate the cell to the required size, the function returns NULL.

If successful, the function returns a pointer to the reallocated cell. The reallocated cell may be at a different location from the original cell, i.e. the returned pointer may be different to the value of aCell. However, if the cell is smaller than the original, it is guaranteed not to move.

If the location of the new cell is different to that of the original cell, the content of the original cell is copied to the reallocated cell.

If reallocation fails, the content of the original cell is preserved.

If aCell is not NULL, it must point to a valid cell, otherwise the function raises a USER 42 panic.

If aCell contains a NULL pointer, this function allocates a new cell from the heap and the behaviour is the same as Alloc().

Notes:

• The maximum permitted unsigned value of aSize is defined as the unsigned value of KMaxTInt/2. Passing an unsigned value greater than this causes the functions to raise a USER 47 panic. For example, calling ReAlloc(someptr,-1) causes a panic.

• 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 value must not be negative, otherwise the functions raise a USER 54 panic.

Return value

TAny* A pointer to the reallocated cell. NULL if ReAlloc() called and insufficient memory available.

TAny* ReAllocL(TAny* aCell,TInt aSize);

Description

Increases or decreases the size of a cell to a specified value. If there is insufficient memory available in the heap from which to reallocate the cell to the required size the function leaves.

If successful, the function returns a pointer to the reallocated cell. The reallocated cell may be at a different location from the original cell, i.e. the returned pointer may be different to the value of aCell. However, if the cell is smaller than the original, it is guaranteed not to move.

If the location of the new cell is different to that of the original cell, the content of the original cell is copied to the reallocated cell.

If reallocation fails, the content of the original cell is preserved.

If aCell is not NULL, it must point to a valid cell, otherwise the functions raise a USER 42 panic.

If aCell contains a NULL pointer, the function allocates a new cell from the heap and its behaviour is the same as AllocL().

Notes:

• The maximum permitted unsigned value of aSize is defined as the unsigned value of KMaxTInt/2. Passing an unsigned value greater than this causes the functions to raise a USER 47 panic. For example, calling ReAlloc(someptr,-1) raises a panic.

• 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 value must not be negative, otherwise the functions raise a USER 54 panic.

Return value

TAny* A pointer to the reallocated cell. NULL if ReAlloc() is called and there is insufficient memory available.

TAny* Adjust(TAny* aCell,TInt anOffset,TInt aDelta);

Description

Stretches or shrinks a cell by a specified amount at an offset from the start of the cell. If necessary, the cell is reallocated. If there is insufficient memory available in the heap from which to reallocate the cell to the required size, the function returns NULL.

Shrinking of the cell occurs when aDelta is negative and means the removal of (the magnitude of) aDelta bytes from the cell, starting at offset anOffset from the start of the cell.

Stretching a cell occurs when aDelta is positive and means the insertion of aDelta bytes into the cell at offset anOffset from the start of the cell and copying the original content of the cell at offset anOffset to offset anOffset+aDelta.

If successful, the functions return a pointer to the adjusted cell. The adjusted cell may be at a different location from the original cell, i.e. the returned pointer may be different to the value of aCell.

If adjustment fails, the content of the original cell is preserved.

Notes:

• The value of anOffset must not be negative, otherwise the functions raise a USER 52 panic

• aCell cannot be NULL.

• The functions accept a zero value of aDelta, but does not result in any change to the allocated cell.

• The resulting size of the adjusted cell may be rounded up.

Parameters

TAny* aCell A pointer to the cell to be adjusted. TInt anOffset The offset from the start of the cell where adjustment is to be made TInt aDelta The amount by which the cell is to be stretched, if positive, or shrunk, if negative.

Return value

TAny* A pointer to the adjusted cell. NULL if insufficient memory is available.

TAny* AdjustL(TAny* aCell,TInt anOffset,TInt aDelta);

Description

Stretches or shrinks a cell by a specified amount at an offset from the start of the cell. If necessary, the cell is reallocated. If there is insufficient memory available in the heap from which to reallocate the cell to the required size the function leaves.

Shrinking of the cell occurs when aDelta is negative and means the removal of (the magnitude of) aDelta bytes from the cell, starting at offset anOffset from the start of the cell.

Stretching a cell occurs when aDelta is positive and means the insertion of aDelta bytes into the cell at offset anOffset from the start of the cell and copying the original content of the cell at offset anOffset to offset anOffset+aDelta.

If successful, the functions return a pointer to the adjusted cell. The adjusted cell may be at a different location from the original cell, i.e. the returned pointer may be different to the value of aCell.

If adjustment fails, the content of the original cell is preserved.

Notes:

• The value of anOffset must not be negative, otherwise the functions raise a USER 52 panic

• aCell cannot be NULL.

• The functions accept a zero value of aDelta, but does not result in any change to the allocated cell.

• The resulting size of the adjusted cell may be rounded up.

Parameters

TAny* aCell A pointer to the cell to be adjusted. TInt anOffset The offset from the start of the cell where adjustment is to be made. TInt aDelta The amount by which the cell is to be stretched, if positive, or shrunk, if negative.

Return value

TAny* A pointer to the adjusted cell. NULL ifAdjust() is called and there is insufficient memory available.

void Free(TAny* aCell);

Description

Frees the cell and returns it to the heap.

If aCell is not NULL, it must point to a valid cell, otherwise the function raises a USER 42 panic.

The function accepts, but ignores a NULLpointer.

Parameters

TAny* aCell A pointer to a valid cell to be freed. This may be NULL.

void FreeZ(TAny*& aCell);

Description

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

The specified pointer can be NULL but, otherwise, must point to a valid cell, otherwise the function raises a USER 42 panic.

The function ignores a reference to a NULL pointer.

Parameters

TAny*& aCell A reference to a pointer to a valid cell to be freed. The referenced pointer may be NULL.

void FreeAll();

Description

Frees all allocated cells on this heap.

TInt AllocLen(const TAny* aCell) const;

Description

Returns the length of the specified allocated heap cell. aCell must point to a valid cell otherwise a USER 42 panic may be raised.

Parameters

const TAny* aCell A pointer to the allocated cell whose length is to be fetched

Return value

TInt The length of the allocated cell.

TInt AllocSize(TInt& aTotalAllocSize) const;

Description

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

Parameters

TInt& aTotalAllocSize On return, this reference contains the total space allocated to the cells.

Return value

TInt The number of cells currently allocated on this heap.

THeapType Type() const;

Description

Returns the type of this heap.

Return value

THeapType The type of heap.

TUint8* Base() const;

Description

Returns a pointer to the start of the heap.

Note that because of the small space overhead incurred by all allocated cells, no cell will have the same address as that returned by this function.

Return value

TUint8* A pointer to the base of the heap.

TInt Size() const;

Description

Returns the current size of the heap. This is the total number of bytes committed by the host chunk.

Note that this value is always greater than the total space available across all allocated cells.

Return value

TInt The size of the heap

TInt Available(TInt& aBiggestBlock) const;

Description

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

TInt& aBiggestBlock On return, this reference contains the space available in the largest free block on the heap.

Return value

TInt The total free space currently available on the heap.

TInt Count() const;
TInt Count(TInt& aFreeCount) const;

Description

Returns the total number of cells allocated on this heap.

Parameters

TInt& aFreeCount If specified, then, on return from this function, this reference contains the number of free cells on this heap.

Return value

TInt The number of cells allocated on this heap

TInt Compress();

Description

Compresses the heap. This 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

TInt The space reclaimed. If no space can be reclaimed, then this value is zero.

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.

If any corruption is found, the function raises either a USER 48 or a USER 49 panic.

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 __DbgStartCheck() has been freed.

Note:

• The behaviour described here only applies to debug builds. In release builds, the implementation is effectively empty.

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 __DbgStartCheck() has been freed.

If the check fails and this is a user heap, the function raises an ALLOC: nnnnnnnn panic, where nnnnnnnn is a hexadecimal pointer to the first orphaned heap cell.

If the check fails and this is a Kernel heap, the Kernel server raises a KERN-SVR 17 panic.

Note:

• The behaviour described here only applies to debug builds. In release builds, the implementation just returns a zero value.

Parameters

TInt aCount The number of allocated heap cells expected.

Return value

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

void __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, 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.

Note:

• The behaviour described here only applies to debug builds. In release builds, the implementation is effectively empty.

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.

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 RHeap::ENone.

Notes:

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

• For failure types RHeap::EFailNext and RHeap::ENone, set aRate to 1.

• The behaviour described here only applies to debug builds. In release builds, the implementation is effectively empty.

Parameters

TAllocFail aType An enumeration which indicates how to simulate heap allocation failure. TInt aValue The rate of failure;when aType is RHeap::EDeterministic, heap allocation fails every aRate attempt

TDbgHeapType

Description

Heap debug checking type flag.

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

TAllocFail

Description

Heap allocation failure flags. This enumeration indicates how to simulate heap allocation failure.

See also:

• RHeap::__DbgSetAllocFail()

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.

typedef TUint32 TAllocSize;

Description

Size of the allocated cell header for release builds.