UserHeap Class Reference

class UserHeap

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

RHeap RChunk

Public Member Functions
IMPORT_C RHeap *ChunkHeap(const TDesC *, TInt, TInt, TInt, TInt, TBool)
IMPORT_C RHeap *ChunkHeap(RChunk, TInt, TInt, TInt, TInt, TBool, TUint32)
IMPORT_C RHeap *ChunkHeap(const TChunkHeapCreateInfo &)
IMPORT_C TIntCreateThreadHeap(SStdEpocThreadCreateInfo &, RHeap *&, TInt, TBool)
IMPORT_C RHeap *FixedHeap(TAny *, TInt, TInt, TBool)
IMPORT_C RHeap *OffsetChunkHeap(RChunk, TInt, TInt, TInt, TInt, TInt, TBool, TUint32)
IMPORT_C TIntSetupThreadHeap(TBool, SStdEpocThreadCreateInfo &)
Public Member Enumerations
enumTChunkHeapCreateMode { EChunkHeapSwitchTo = 0x1, EChunkHeapDuplicate = 0x2, EChunkHeapMask = EChunkHeapSwitchTo | EChunkHeapDuplicate }

Member Functions Documentation

ChunkHeap(const TDesC *, TInt, TInt, TInt, TInt, TBool)

IMPORT_C RHeap *ChunkHeap(const TDesC *aName,
TIntaMinLength,
TIntaMaxLength,
TIntaGrowBy = 1,
TIntaAlign = 0,
TBoolaSingleThread = EFalse
)[static]

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.

panic
USER 41 if aMinLength is greater than the supplied value of aMaxLength.
panic
USER 55 if aMinLength is negative.
panic
USER 172 if aAlign is not a power of 2 or is less than the size of a TAny*.

Parameters

const TDesC * aNameIf 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 aMinLengthThe minimum length of the heap.
TInt aMaxLengthThe 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 = 1The increments to the size of the host chunk. If a value is not explicitly specified, the value KMinHeapGrowBy is taken by default
TInt aAlign = 0The alignment of heap cells.
TBool aSingleThread = EFalseIndicates whether single threaded or not.

ChunkHeap(RChunk, TInt, TInt, TInt, TInt, TBool, TUint32)

IMPORT_C RHeap *ChunkHeap(RChunkaChunk,
TIntaMinLength,
TIntaGrowBy = 1,
TIntaMaxLength = 0,
TIntaAlign = 0,
TBoolaSingleThread = EFalse,
TUint32aMode = 0
)[static]

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

panic
USER 172 if aAlign is not a power of 2 or is less than the size of a TAny*.

Parameters

RChunk aChunkThe chunk that will host the heap.
TInt aMinLengthThe minimum length of the heap.
TInt aGrowBy = 1The increments to the size of the host chunk.
TInt aMaxLength = 0The maximum length to which the heap can grow.
TInt aAlign = 0The alignment of heap cells.
TBool aSingleThread = EFalseIndicates whether single threaded or not.
TUint32 aMode = 0Flags controlling the heap creation. This should be set from one or more of the values in TChunkHeapCreateMode.

ChunkHeap(const TChunkHeapCreateInfo &)

IMPORT_C RHeap *ChunkHeap(const TChunkHeapCreateInfo &aCreateInfo)[static]

Creates a chunk heap of the type specified by the parameter aCreateInfo.

panic
USER 41 if the heap's specified minimum length is greater than the specified maximum length.
panic
USER 55 if the heap's specified minimum length is negative.
panic
USER 172 if the heap's specified alignment is not a power of 2 or is less than the size of a TAny*.

Parameters

const TChunkHeapCreateInfo & aCreateInfoA reference to a TChunkHeapCreateInfo object specifying the type of chunk heap to create.

CreateThreadHeap(SStdEpocThreadCreateInfo &, RHeap *&, TInt, TBool)

IMPORT_C TIntCreateThreadHeap(SStdEpocThreadCreateInfo &aInfo,
RHeap *&aHeap,
TIntaAlign = 0,
TBoolaSingleThread = EFalse
)[static]

Parameters

SStdEpocThreadCreateInfo & aInfo
RHeap *& aHeap
TInt aAlign = 0
TBool aSingleThread = EFalse

FixedHeap(TAny *, TInt, TInt, TBool)

IMPORT_C RHeap *FixedHeap(TAny *aBase,
TIntaMaxLength,
TIntaAlign = 0,
TBoolaSingleThread = ETrue
)[static]

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.

panic
USER 56 if aMaxLength is negative.
panic
USER 172 if aAlign is not a power of 2 or is less than the size of a TAny*.

Parameters

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

OffsetChunkHeap(RChunk, TInt, TInt, TInt, TInt, TInt, TBool, TUint32)

IMPORT_C RHeap *OffsetChunkHeap(RChunkaChunk,
TIntaMinLength,
TIntaOffset,
TIntaGrowBy = 1,
TIntaMaxLength = 0,
TIntaAlign = 0,
TBoolaSingleThread = EFalse,
TUint32aMode = 0
)[static]

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.

panic
USER 172 if aAlign is not a power of 2 or is less than the size of a TAny*.

Parameters

RChunk aChunkThe chunk that will host the heap.
TInt aMinLengthThe minimum length of the heap.
TInt aOffsetThe offset from the start of the chunk, to the start of the heap.
TInt aGrowBy = 1The increments to the size of the host chunk.
TInt aMaxLength = 0The maximum length to which the heap can grow.
TInt aAlign = 0The alignment of heap cells.
TBool aSingleThread = EFalseIndicates whether single threaded or not.
TUint32 aMode = 0Flags controlling the heap creation. This should be set from one or more of the values in TChunkHeapCreateMode.

SetupThreadHeap(TBool, SStdEpocThreadCreateInfo &)

IMPORT_C TIntSetupThreadHeap(TBoolaNotFirst,
SStdEpocThreadCreateInfo &aInfo
)[static]

Parameters

TBool aNotFirst
SStdEpocThreadCreateInfo & aInfo

Member Enumerations Documentation

Enum TChunkHeapCreateMode

Flags to control the heap creation.

Enumerators

EChunkHeapSwitchTo = 0x1

On successful creation of the heap this switches the calling thread to use the new heap.

EChunkHeapDuplicate = 0x2

On successful creation of the heap this causes the handle to the heap to be duplicated.

EChunkHeapMask = EChunkHeapSwitchTo | EChunkHeapDuplicate