![[Index]](../../../stock/btn_index.gif){kind=small}
![[Glossary]](../../../stock/btn_glossary.gif){kind=small}
![[Previous]](../../../stock/btn_prev.gif){kind=small}
![[Next]](../../../stock/btn_next.gif){kind=small}
| |
|
| |
Location:
e32std.h
Link against: euser.lib
RHeap
Supported from 5.0
Represents a heap. The heap itself is contained in a chunk and may be the only occupant of the chunk or may share the chunk with the program stack.
The class contains member functions for allocating, adjusting, freeing individual cells and generally managing the heap.
The class is not a handle in the same sense that
RChunk is a handle; i.e. there is no Kernel object which
corresponds to the heap.
|
Defined in RHeap:
Adjust(), AdjustL(), Alloc(), AllocL(), AllocLC(), AllocLen(), AllocSize(), Available(), Base(), Check(), Close(), Compress(), Count(), EDeterministic, EFailNext, EKernel, ENone, ERandom, ETrueRandom, EUser, Free(), FreeAll(), FreeZ(), Open(), ReAlloc(), ReAllocL(), Size(), TAllocFail, TAllocSize, TDbgHeapType, Type(), __DbgMarkCheck(), __DbgMarkEnd(), __DbgMarkStart(), __DbgSetAllocFail()
Inherited from RHeapBase:
EChunkNormal,
EChunkStack,
EChunkSupervisor,
EFixedAddress,
THeapType
TInt Open();
Opens this heap for shared access. Opening the heap increases the heap's access count by one.
The heap must be of type EChunkNormal otherwise
the function raises a USER 58 panic.
|
void Close();
Closes this shared heap. Closing the heap decreases the heap's access count by one. If the access reaches zero, the hosting chunk is closed.
Notes:
The heap must be of type EChunkNormal otherwise
the function is not honoured and the close is not performed.
Trying to close the heap if the access count is already zero, raises a USER 57 panic.
|
TAny* Alloc(TInt aSize);
Allocates a cell of a specified size from the heap. If there is
insufficient memory available on the heap from which to allocate a cell of the
required size, the function returns NULL.
Notes:
The maximum unsigned value of aSize must be less
than the value of KMaxTInt/2. Passing an unsigned value greater
than or equal to KMaxTInt/2 causes the functions to raise a USER
47 panic. For example, calling Alloc(-1) raises a panic.
The resulting size of the allocated cell may be rounded up to a
value greater than aSize, but is guaranteed to be not less than
aSize.
|
|
TAny* AllocL(TInt aSize);
Allocates a cell of a specified size from the heap.
If there is insufficient memory available on the heap from which to allocate a cell of the required size, the function leaves.
Notes:
The maximum unsigned value of aSize must be less
than the value of KMaxTInt/2. Passing an unsigned value greater
than or equal to KMaxTInt/2 causes the functions to raise a USER
47 panic. For example, calling AllocL(-1) causes a panic.
The resulting size of the allocated cell may be rounded up to a
value greater than aSize, but is guaranteed to be not less than
aSize.
|
|
TAny* AllocLC(TInt aSize);
Allocates a cell of a specified size from the heap and, if successful, places a pointer to the cell onto the cleanup stack.
If there is insufficient memory available on the heap from which to allocate a cell of the required size, this function leaves.
Notes:
The maximum unsigned value of aSize must be less than
the value of KMaxTInt/2. Passing an unsigned value greater than or
equal to KMaxTInt/2 causes the functions to raise a USER 47 panic.
For example, calling AllocLC(-1) causes a panic.
The resulting size of the allocated cell may be rounded up to a
value greater than aSize, but is guaranteed to be not less than
aSize.
|
|
TAny* ReAlloc(TAny* aCell,TInt aSize);
Increases or decreases the size of the existing cell to the new value. If
there is insufficient memory available in the heap from which to reallocate the
cell to the required size, the function returns NULL.
If successful, the function returns a pointer to the reallocated cell.
The reallocated cell may be at a different location from the original cell,
i.e. the returned pointer may be different to the value of aCell.
However, if the cell is smaller than the original, it is guaranteed not to
move.
If the location of the new cell is different to that of the original cell, the content of the original cell is copied to the reallocated cell.
If reallocation fails, the content of the original cell is preserved.
If aCell is not NULL, it must point to a valid
cell, otherwise the function raises a USER 42 panic.
If aCell contains a NULL pointer, this function
allocates a new cell from the heap and the behaviour is the same as
Alloc().
Notes:
The maximum permitted unsigned value of aSize is defined
as the unsigned value of KMaxTInt/2. Passing an unsigned value
greater than this causes the functions to raise a USER 47 panic. For example,
calling ReAlloc(someptr,-1) causes a panic.
The resulting size of the re-allocated cell may be rounded up to a
value greater than aSize, but is guaranteed to be not less than
aSize.
|
|
TAny* ReAllocL(TAny* aCell,TInt aSize);
Increases or decreases the size of a cell to a specified value. If there is insufficient memory available in the heap from which to reallocate the cell to the required size the function leaves.
If successful, the function returns a pointer to the reallocated cell.
The reallocated cell may be at a different location from the original cell,
i.e. the returned pointer may be different to the value of aCell.
However, if the cell is smaller than the original, it is guaranteed not to
move.
If the location of the new cell is different to that of the original cell, the content of the original cell is copied to the reallocated cell.
If reallocation fails, the content of the original cell is preserved.
If aCell is not NULL, it must point to a valid
cell, otherwise the functions raise a USER 42 panic.
If aCell contains a NULL pointer, the function
allocates a new cell from the heap and its behaviour is the same
asAllocL().
Notes:
The maximum permitted unsigned value of aSize is defined
as the unsigned value of KMaxTInt/2. Passing an unsigned value
greater than this causes the functions to raise a USER 47 panic. For example,
calling ReAlloc(someptr,-1) raises a panic.
The resulting size of the re-allocated cell may be rounded up to a
value greater than aSize, but is guaranteed to be not less than
aSize.
|
|
TAny* Adjust(TAny* aCell,TInt anOffset,TInt aDelta);
Stretches or shrinks a cell by a specified amount at an offset from the
start of the cell. If necessary, the cell is reallocated. If there is
insufficient memory available in the heap from which to reallocate the cell to
the required size, the function returns NULL.
Shrinking of the cell occurs when aDelta is negative and
means the removal of (the magnitude of) aDelta bytes from the
cell, starting at offset anOffset from the start of the
cell.
Stretching a cell occurs when aDelta is positive and means
the insertion of aDelta bytes into the cell at
offsetanOffset from the start of the cell and copying the original
content of the cell at offset anOffset to
offsetanOffset+aDelta.
If successful, the functions return a pointer to the adjusted cell. The
adjusted cell may be at a different location from the original cell, i.e. the
returned pointer may be different to the value of aCell.
If adjustment fails, the content of the original cell is preserved.
Notes:
The value of anOffset must not be negative, otherwise the
functions raise a USER 52 panic
aCell cannot be NULL.
The functions accept a zero value of aDelta, but does not
result in any change to the allocated cell.
The resulting size of the adjusted cell may be rounded up.
|
|
TAny* AdjustL(TAny* aCell,TInt anOffset,TInt aDelta);
Stretches or shrinks a cell by a specified amount at an offset from the start of the cell. If necessary, the cell is reallocated. If there is insufficient memory available in the heap from which to reallocate the cell to the required size the function leaves.
Shrinking of the cell occurs when aDelta is negative and
means the removal of (the magnitude of) aDelta bytes from the
cell, starting at offset anOffset from the start of the
cell.
Stretching a cell occurs when aDelta is positive and means
the insertion of aDelta bytes into the cell at
offsetanOffset from the start of the cell and copying the original
content of the cell at offset anOffset to
offsetanOffset+aDelta.
If successful, the functions return a pointer to the adjusted cell. The
adjusted cell may be at a different location from the original cell, i.e. the
returned pointer may be different to the value of aCell.
If adjustment fails, the content of the original cell is preserved.
Notes:
The value of anOffset must not be negative, otherwise the
functions raise a USER 52 panic
aCell cannot be NULL.
The functions accept a zero value of aDelta, but does not
result in any change to the allocated cell.
The resulting size of the adjusted cell may be rounded up.
|
|
void Free(TAny* aCell);
Frees the cell and returns it to the heap.
If aCell is not NULL, it must point to a valid
cell, otherwise the function raises a USER 42 panic.
The function accepts, but ignores a
NULLpointer.
|
void FreeZ(TAny*& aCell);
Frees the specified cell, returns it to the heap and resets the pointer
to NULL.
The specified pointer can be NULL but, otherwise, must point to a valid cell, otherwise the function raises a USER 42 panic.
The function ignores a reference to a
NULLpointer.
|
|
TInt AllocLen(const TAny* aCell) const;
Returns the length of the specified allocated heap
cell.aCell must point to a valid cell otherwise a USER 42 panic
may be raised.
|
|
TInt AllocSize(TInt& aTotalAllocSize) const;
Returns the total number of cells allocated on this heap and the total space allocated to them.
|
|
THeapType Type() const;
Returns the type of this heap.
|
TUint8* Base() const;
Returns a pointer to the start of the heap.
Note that because of the small space overhead incurred by all allocated cells, no cell will have the same address as that returned by this function.
|
TInt Size() const;
Returns the current size of the heap. This is the total number of bytes committed by the host chunk.
Note that this value is always greater than the total space available across all allocated cells.
|
TInt Available(TInt& aBiggestBlock) const;
Returns the the total free space currently available on the heap and the space available in the largest free block.
The space available represents the total space which can be allocated.
Note that compressing the heap may reduce the total free space available and the space available in the largest free block.
|
|
TInt Count() const;
TInt Count(TInt& aFreeCount) const;
Returns the total number of cells allocated on this heap.
|
|
|
TInt Compress();
Compresses the heap. This function frees excess committed space from the top of the heap. The size of the heap is never reduced below the minimum size specified during creation of the heap.
|
void Check() const;
Checks the validity of the heap.
The function walks through the list of allocated cells and the list of free cells checking that this heap is consistent and complete.
If any corruption is found, the function raises either a USER 48 or a USER 49 panic.
|
void __DbgMarkStart();
Marks the start of heap cell checking for this heap.
If earlier calls to __DbgMarkStart() have been made, then
this call to __DbgMarkStart() marks the start of a new nested
level of heap cell checking.
Every call to __DbgMarkStart() should be matched by a later
call to __DbgMarkEnd() to verify that the number of heap cells
allocated, at the current nested level, is as expected. This expected number of
heap cells is passed to __DbgMarkEnd() as a parameter; however,
the most common expected number is zero, reflecting the fact that most
developers check that all memory allocated since a previous call
to__DbgStartCheck() has been freed.
Note:
The behaviour described here only applies to debug builds. In release builds, the implementation is effectively empty.
TUint32 __DbgMarkEnd(TInt aCount);
Marks the end of heap cell checking at the current nested level for this heap.
A call to this function should match an earlier call
to__DbgMarkStart(). If there are more calls to this function than
calls to __DbgMarkStart(), then this function raises a USER 51
panic.
The function checks that the number of heap cells allocated, at the
current nested level, is aCount. The most common value
foraCount is zero, reflecting the fact that most developers check
that all memory allocated since a previous call
to__DbgStartCheck() has been freed.
If the check fails and this is a user heap, the function raises
anALLOC: nnnnnnnn panic, where nnnnnnnn is a
hexadecimal pointer to the first orphaned heap cell.
If the check fails and this is a Kernel heap, the Kernel server raises a KERN-SVR 17 panic.
Note:
The behaviour described here only applies to debug builds. In release builds, the implementation just returns a zero value.
|
|
void __DbgMarkCheck(TBool aCountAll,TInt aCount,const TDesC8& aFileName,TInt aLineNum);
Checks the current number of allocated heap cells for this heap.
If aCountAll is true, the function checks that the total
number of allocated cells on this heap is the same as aCount.
IfaCountAll is false, the function checks that the number of
allocated cells at the current nested level is the same
asaCount.
If checking fails, the function raises a panic; information about the failure is put into the panic category; this takes the form:
ALLOC COUNT\rExpected aaa\rAllocated bbb\rLn: ccc
ddddd
where
aaaa is the value aCount
bbbb is the number of allocated heap cells
ccc is a line number, copied
fromaLineNum
ddddd is a file name, copied from the
descriptoraFileName
Note that the panic number is 1.
Note:
The behaviour described here only applies to debug builds. In release builds, the implementation is effectively empty.
|
void __DbgSetAllocFail(TAllocFail aType,TInt aValue);
Simulates a heap allocation failure for this heap.
The failure occurs on subsequent calls to new or any of the
functions which allocate memory from this heap.
The timing of the allocation failure depends on the type of allocation
failure requested, i.e. on the value of aType.
The simulation of heap allocation failure is cancelled
ifaType is given the value RHeap::ENone.
Notes:
If the failure type is RHeap::EFailNext, the next attempt to
allocate from this heap fails; however, no further failures will occur.
For failure types RHeap::EFailNext
andRHeap::ENone, set aRate to 1.
The behaviour described here only applies to debug builds. In release builds, the implementation is effectively empty.
|
|
TDbgHeapType
Heap debug checking type flag.
|
TAllocFail
Heap allocation failure flags. This enumeration indicates how to simulate heap allocation failure.
|
|
typedef TUint32 TAllocSize;
Size of the allocated cell header for release builds.
Copyright ©2002 Symbian Ltd. 6.1-00174 |
|
![[Top]](../../../stock/arrow_up_2.gif){kind=icon}
![[Top]](../../../stock/arrow_up.gif){kind=icon}