#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 RHeap * | ChunkHeap(const TChunkHeapCreateInfo &, const THeapConfigParms &) |
| 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 &) |
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 |
| 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.
| Parameters | |
|---|---|
| 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 in bytes. This will be rounded up to the nearest page size by the allocator. |
| aMaxLength | The maximum length in bytes to which the heap can grow. This will be rounded up to the nearest page size by the allocator. |
| aGrowBy | The number of bytes by which the heap will grow when more memory is required. This will be rounded up to the nearest page size by the allocator. If a value is not explicitly specified, the page size is taken by default. |
| aAlign | From Symbian^4 onwards, this value is ignored but EABI 8 byte alignment is guaranteed for all allocations 8 bytes or more in size. 4 byte allocations will be aligned to a 4 byte boundary. Best to pass in zero. |
| aSingleThread | EFalse if the heap is to be accessed from multiple threads. This will cause internal locks to be created, guaranteeing thread safety. |
| Panic Codes | |
|---|---|
| USER | 41 if aMaxLength is < aMinLength. |
| USER | 55 if aMinLength is negative. |
| USER | 56 if aMaxLength is negative. |
| 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.
See also: UserHeap::OffsetChunkHeap()
| Parameters | |
|---|---|
| aChunk | The chunk that will host the heap. |
| aMinLength | The minimum length of the heap in bytes. This will be rounded up to the nearest page size by the allocator. |
| aGrowBy | The number of bytes by which the heap will grow when more memory is required. This will be rounded up to the nearest page size by the allocator. If a value is not explicitly specified, the page size is taken by default. |
| aMaxLength | The maximum length in bytes to which the heap can grow. This will be rounded up to the nearest page size by the allocator. If 0 is passed in, the maximum lengt of the chunk is used. |
| aAlign | From Symbian^4 onwards, this value is ignored but EABI 8 byte alignment is guaranteed for all allocations 8 bytes or more in size. 4 byte allocations will be aligned to a 4 byte boundary. Best to pass in zero. |
| aSingleThread | EFalse if the heap is to be accessed from multiple threads. This will cause internal locks to be created, guaranteeing thread safety. |
| aMode | Flags controlling the heap creation. See RAllocator::TFlags. |
| IMPORT_C RHeap * | ChunkHeap | ( | const TChunkHeapCreateInfo & | aCreateInfo | ) | [static] |
Creates a chunk heap of the type specified by the parameter aCreateInfo.
| Parameters | |
|---|---|
| aCreateInfo | A reference to a TChunkHeapCreateInfo object specifying the type of chunk heap to create. |
| Panic Codes | |
|---|---|
| USER | 41 if the heap's specified minimum length is greater than the specified maximum length. |
| USER | 55 if the heap's specified minimum length is negative. |
| USER | 172 if the heap's specified alignment is not a power of 2 or is less than the size of a TAny*. |
| IMPORT_C RHeap * | ChunkHeap | ( | const TChunkHeapCreateInfo & | aCreateInfo, |
| const THeapConfigParms & | aConfigParms | |||
| ) | [static] | |||
Creates a chunk heap of the type specified by the parameters aCreateInfo and aConfigParms.
| Parameters | |
|---|---|
| aCreateInfo | A reference to a TChunkHeapCreateInfo object specifying the type of chunk heap to create. |
| aConfigParms | A reference to a THeapConfigParms object specifying the parameters depending on the heap type. |
| Panic Codes | |
|---|---|
| USER | 41 if the heap's specified minimum length is greater than the specified maximum length. |
| USER | 55 if the heap's specified minimum length is negative. |
| USER | 172 if the heap's specified alignment is not a power of 2 or is less than the size of a TAny*. |
| IMPORT_C TInt | CreateThreadHeap | ( | SStdEpocThreadCreateInfo & | aInfo, |
| RHeap *& | aHeap, | |||
| TInt | aAlign = 0, | |||
| TBool | aSingleThread = EFalse | |||
| ) | [static] | |||
| 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, the heap is ready to use. This assumes that the memory pointed to by aBase is mapped and able to be used. You must ensure that you pass in a large enough value for aMaxLength. Passing in a value that is too small to hold the metadata for the heap (~1 KB) will result in the size being rounded up and the heap thereby running over the end of the memory assigned to it. But then if you were to pass in such as small value then you would not be able to do any allocations from the heap anyway. Moral of the story: Use a sensible value for aMaxLength!
| Parameters | |
|---|---|
| aBase | A pointer to the location where the heap is to be constructed. |
| aMaxLength | The maximum length in bytes to which the heap can grow. If the supplied value is too small to hold the heap's metadata, it will be increased. |
| aAlign | From Symbian^4 onwards, this value is ignored but EABI 8 byte alignment is guaranteed for all allocations 8 bytes or more in size. 4 byte allocations will be aligned to a 4 byte boundary. Best to pass in zero. |
| aSingleThread | EFalse if the heap is to be accessed from multiple threads. This will cause internal locks to be created, guaranteeing thread safety. |
| Panic Codes | |
|---|---|
| USER | 56 if aMaxLength is negative. |
| 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 using a chunk which has some of its memory already used, at the start of that that chunk. The maximum length to which the heap can grow is the maximum size of the chunk, minus the data at the start of the chunk.
The offset at which to create the heap is passed in as the aOffset parameter. Legacy heap implementations always respected the aOffset value, however more modern heap implementations are more sophisticated and cannot necessarily respect this value. Therefore, if possible, you should always use an aOffset of 0 unless you have a very explicit requirement for using a non zero value. Using a non zero value will result in a less efficient heap algorithm being used in order to respect the offset.
Another issue to consider when using this function is the type of the chunk passed in. In order for the most efficient heap algorithms to be used, the chunk passed in should always be a disconnected chunk. Passing in a non disconnected chunk will again result in a less efficient heap algorithm being used.
Finally, another requirement for the most efficient heap algorithms to be used is for the heap to be able to expand. Therefore, unless you have a specific reason to do so, always specify aMaxLength > aMinLength.
So, if possible, use aOffset == zero, aMaxLength > aMinLength and a disconnected chunk for best results!
| Parameters | |
|---|---|
| aChunk | The chunk that will host the heap. |
| aMinLength | The minimum length of the heap in bytes. This will be rounded up to the nearest page size by the allocator. |
| aOffset | The offset in bytes from the start of the chunk at which to create the heap. If used (and it shouldn't really be!) then it will be rounded up to a multiple of 8, to respect EABI 8 byte alignment requirements. |
| aGrowBy | The number of bytes by which the heap will grow when more memory is required. This will be rounded up to the nearest page size by the allocator. If a value is not explicitly specified, the page size is taken by default. |
| aMaxLength | The maximum length in bytes to which the heap can grow. This will be rounded up to the nearest page size by the allocator. If 0 is passed in, the maximum length of the chunk is used. |
| aAlign | From Symbian^4 onwards, this value is ignored but EABI 8 byte alignment is guaranteed for all allocations 8 bytes or more in size. 4 byte allocations will be aligned to a 4 byte boundary. Best to pass in zero. |
| aSingleThread | EFalse if the heap is to be accessed from multiple threads. This will cause internal locks to be created, guaranteeing thread safety. |
| aMode | Flags controlling the heap creation. See RAllocator::TFlags. |
| Panic Codes | |
|---|---|
| USER | 41 if aMaxLength is < aMinLength. |
| USER | 55 if aMinLength is negative. |
| USER | 56 if aMaxLength is negative. |
| USER | 168 if aOffset is negative. |