Collapse all Symbian^3 Application Developer Library

UserHeap Class Reference

class UserHeap

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

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 TInt	CreateThreadHeap ( 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 TInt	SetupThreadHeap ( TBool , SStdEpocThreadCreateInfo &)

Public Member Enumerations
enum	TChunkHeapCreateMode { 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,
			TInt	aMinLength,
			TInt	aMaxLength,
			TInt	aGrowBy = 1,
			TInt	aAlign = 0,
			TBool	aSingleThread = 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 * 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 = 1	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 = 0	The alignment of heap cells.
TBool aSingleThread = EFalse	Indicates whether single threaded or not.

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

IMPORT_C RHeap *	ChunkHeap	(	RChunk	aChunk,
			TInt	aMinLength,
			TInt	aGrowBy = 1,
			TInt	aMaxLength = 0,
			TInt	aAlign = 0,
			TBool	aSingleThread = EFalse,
			TUint32	aMode = 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 aChunk	The chunk that will host the heap.
TInt aMinLength	The minimum length of the heap.
TInt aGrowBy = 1	The increments to the size of the host chunk.
TInt aMaxLength = 0	The maximum length to which the heap can grow.
TInt aAlign = 0	The alignment of heap cells.
TBool aSingleThread = EFalse	Indicates whether single threaded or not.
TUint32 aMode = 0	Flags 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 & aCreateInfo

A reference to a TChunkHeapCreateInfo object specifying the type of chunk heap to create.

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

IMPORT_C TInt	CreateThreadHeap	(	SStdEpocThreadCreateInfo &	aInfo,
			RHeap *&	aHeap,
			TInt	aAlign = 0,
			TBool	aSingleThread = EFalse
		)	[static]

Parameters

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

FixedHeap(TAny *, TInt, TInt, TBool)

IMPORT_C RHeap *	FixedHeap	(	TAny *	aBase,
			TInt	aMaxLength,
			TInt	aAlign = 0,
			TBool	aSingleThread = 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 * 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 = 0	The alignment of heap cells.
TBool aSingleThread = ETrue	Indicates whether single threaded or not.

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

IMPORT_C RHeap *	OffsetChunkHeap	(	RChunk	aChunk,
			TInt	aMinLength,
			TInt	aOffset,
			TInt	aGrowBy = 1,
			TInt	aMaxLength = 0,
			TInt	aAlign = 0,
			TBool	aSingleThread = EFalse,
			TUint32	aMode = 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 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 = 1	The increments to the size of the host chunk.
TInt aMaxLength = 0	The maximum length to which the heap can grow.
TInt aAlign = 0	The alignment of heap cells.
TBool aSingleThread = EFalse	Indicates whether single threaded or not.
TUint32 aMode = 0	Flags controlling the heap creation. This should be set from one or more of the values in TChunkHeapCreateMode.

SetupThreadHeap(TBool, SStdEpocThreadCreateInfo &)

IMPORT_C TInt	SetupThreadHeap	(	TBool	aNotFirst,
			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