Class UserHeap

class UserHeap;

Description

A set of static functions for constructing fixed length heaps and local or global heaps.

Members

Defined in UserHeap:

• ChunkHeap(RChunk,TInt,TInt,TInt,TInt,TBool,TUint32)Creates a heap in an existing chunk.
• ChunkHeap(const TDesC *,TInt,TInt,TInt,TInt,TBool)Creates a heap in a local or global chunk.
• EChunkHeapDuplicate
• EChunkHeapSwitchTo
• FixedHeap(TAny *,TInt,TInt,TBool)Creates a fixed length heap at a specified location.
• OffsetChunkHeap(RChunk,TInt,TInt,TInt,TInt,TInt,TBool,TUint32)Creates a heap in an existing chunk, offset from the beginning of the chunk.
• TChunkHeapCreateMode

See also:

• RChunkA handle to a chunk.

IMPORT_C static RHeap* FixedHeap(TAny *aBase, TInt aMaxLength, TInt aAlign=0, TBool aSingleThread=ETrue);

Description

Creates a fixed length heap at a specified location.

On successful return from this function, aMaxLength bytes are committed by the chunk. The heap cannot be extended.

Parameters

TAny *aBase A pointer to the location where the heap is to be constructed. TInt aMaxLength The length of the heap. If the supplied value is less than KMinHeapSize, it is discarded and the value KMinHeapSize is used instead. TInt aAlign The alignment of heap cells. TBool aSingleThread Indicates whether single threaded or not.

Return value

RHeap * A pointer to the new heap, or NULL if the heap could not be created.

Panic codes

USER 56 if aMaxLength is negative.

IMPORT_C static RHeap* ChunkHeap(const TDesC *aName, TInt aMinLength, TInt aMaxLength, TInt aGrowBy=1, TInt aAlign=0, TBool aSingleThread=EFalse);

Description

Creates a heap in a local or global chunk.

The chunk hosting the heap can be local or global.

A local chunk is one which is private to the process creating it and is not intended for access by other user processes. A global chunk is one which is visible to all processes.

The hosting chunk is local, if the pointer aName is NULL, otherwise the hosting chunk is global and the descriptor *aName is assumed to contain the name to be assigned to it.

Ownership of the host chunk is vested in the current process.

A minimum and a maximum size for the heap can be specified. On successful return from this function, the size of the heap is at least aMinLength. If subsequent requests for allocation of memory from the heap cannot be satisfied by compressing the heap, the size of the heap is extended in increments of aGrowBy until the request can be satisfied. Attempts to extend the heap causes the size of the host chunk to be adjusted.

Note that the size of the heap cannot be adjusted by more than aMaxLength.

Parameters

const TDesC16 *aName If NULL, the function constructs a local chunk to host the heap. If not NULL, a pointer to a descriptor containing the name to be assigned to the global chunk hosting the heap. TInt aMinLength The minimum length of the heap. TInt aMaxLength The maximum length to which the heap can grow. If the supplied value is less than KMinHeapSize, then it is discarded and the value KMinHeapSize used instead. TInt aGrowBy The increments to the size of the host chunk. If a value is not explicitly specified, the value KMinHeapGrowBy is taken by default TInt aAlign The alignment of heap cells. TBool aSingleThread Indicates whether single threaded or not.

Return value

RHeap * A pointer to the new heap or NULL if the heap could not be created.

Panic codes

USER 41 if aMinLength is greater than the supplied value of aMaxLength. USER 55 if aMinLength is negative. USER 56 if aMaxLength is negative.

IMPORT_C static RHeap* ChunkHeap(RChunk aChunk, TInt aMinLength, TInt aGrowBy=1, TInt aMaxLength=0, TInt aAlign=0, TBool aSingleThread=EFalse, TUint32 aMode=0);

Description

Creates a heap in an existing chunk.

This function is intended to be used to create a heap in a user writable code chunk as created by a call to RChunk::CreateLocalCode(TInt,TInt,TOwnerType). This type of heap can be used to hold code fragments from a JIT compiler.

The maximum length to which the heap can grow is the same as the maximum size of the chunk.

Parameters

RChunk aChunk The chunk that will host the heap. TInt aMinLength The minimum length of the heap. TInt aGrowBy The increments to the size of the host chunk. TInt aMaxLength The maximum length to which the heap can grow. TInt aAlign The alignment of heap cells. TBool aSingleThread Indicates whether single threaded or not. TUint32 aMode Flags controlling the reallocation. The only bit which has any effect on reallocation 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

RHeap * A pointer to the new heap or NULL if the heap could not be created.

IMPORT_C static RHeap* OffsetChunkHeap(RChunk aChunk, TInt aMinLength, TInt aOffset, TInt aGrowBy=1, TInt aMaxLength=0, TInt aAlign=0, TBool aSingleThread=EFalse, TUint32 aMode=0);

Description

Creates a heap in an existing chunk, offset from the beginning of the chunk.

This function is intended to be used to create a heap where a fixed amount of additional data must be stored at a known location. The additional data can be placed at the base address of the chunk, allowing it to be located without depending on the internals of the heap structure.

The maximum length to which the heap can grow is the maximum size of the chunk, minus the offset.

Parameters

RChunk aChunk The chunk that will host the heap. TInt aMinLength The minimum length of the heap. TInt aOffset The offset from the start of the chunk, to the start of the heap. TInt aGrowBy The increments to the size of the host chunk. TInt aMaxLength The maximum length to which the heap can grow. TInt aAlign The alignment of heap cells. TBool aSingleThread Indicates whether single threaded or not. TUint32 aMode Flags controlling the reallocation. The only bit which has any effect on reallocation 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

RHeap * A pointer to the new heap or NULL if the heap could not be created.

TChunkHeapCreateMode

Description

EChunkHeapSwitchTo EChunkHeapDuplicate