UserHeap Class Reference

#include <e32std.h>

class UserHeap

Public Member Enumerations
enum	TChunkHeapCreateMode { EChunkHeapSwitchTo, EChunkHeapDuplicate, EChunkHeapMask }

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

Detailed Description

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

Member Enumeration Documentation

Enum TChunkHeapCreateMode

Flags to control the heap creation.

Enumerator	Value	Description
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

Member Function 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*.

Parameter	Description
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.
aMinLength	The minimum length of the heap.
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.
aGrowBy	The increments to the size of the host chunk. If a value is not explicitly specified, the value KMinHeapGrowBy is taken by default
aAlign	The alignment of heap cells.
aSingleThread	Indicates whether single threaded or not.

Returns: A pointer to the new heap or NULL if the heap could not be created.

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

Parameter	Description
aChunk	The chunk that will host the heap.
aMinLength	The minimum length of the heap.
aGrowBy	The increments to the size of the host chunk.
aMaxLength	The maximum length to which the heap can grow.
aAlign	The alignment of heap cells.
aSingleThread	Indicates whether single threaded or not.
aMode	Flags controlling the heap creation. This should be set from one or more of the values in TChunkHeapCreateMode.

Returns: A pointer to the new heap or NULL if the heap could not be created.

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

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

Returns: A pointer to the new heap or NULL if the heap could not be created.

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

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

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

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

Returns: A pointer to the new heap, or NULL if the heap could not be created.

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

Parameter	Description
aChunk	The chunk that will host the heap.
aMinLength	The minimum length of the heap.
aOffset	The offset from the start of the chunk, to the start of the heap.
aGrowBy	The increments to the size of the host chunk.
aMaxLength	The maximum length to which the heap can grow.
aAlign	The alignment of heap cells.
aSingleThread	Indicates whether single threaded or not.
aMode	Flags controlling the heap creation. This should be set from one or more of the values in TChunkHeapCreateMode.

Returns: A pointer to the new heap or NULL if the heap could not be created.

SetupThreadHeap ( TBool, SStdEpocThreadCreateInfo & )

IMPORT_C TInt	SetupThreadHeap	(	TBool	aNotFirst,
			SStdEpocThreadCreateInfo &	aInfo
		)	[static]