Class THeapWalk

THeapWalk

Support

Supported from 5.0

Description

Provides the behaviour for walking through the lists of allocated and free cells of a heap to check that the heap is in a consistent state and is not corrupted.

The class is pure virtual and is not intended to be instantiated. Instead, a derived class must be constructed which provides an implementation for the Info() pure virtual function.

Writing derived classes:

The THeapWalk class provides most of the effort for walking the heap. To use it, a derived class must be built which provides an implementation for the Info() function.

Info() is called by the Walk() function for every good allocated cell and every good free cell on the heap together with the address and length of these cells. The derived class can use this information as it sees fit.

In addition, Info() is called when Walk() detects a free cell or an allocated cell which it considers to be bad. In this event, this call to Info() is the last one before Walk() itself terminates.

Defined in THeapWalk:
EBadAllocatedCellAddress, EBadAllocatedCellSize, EBadFreeCellAddress, EGoodAllocatedCell, EGoodFreeCell, Info(), SetValue(), TCellType, THeapWalk(), Value(), Walk()

THeapWalk(const RHeap& aHeap);

Description

Constructs this object taking a reference to the specified heap which is to be checked.

Parameters

const RHeap& aHeap A reference to the heap which is to be walked through.

TInt Walk();

Description

Walks through the entire heap.

The function walks through the list of allocated cells and the list of free cells checking that the addresses and lengths of both allocated cells and free cells are consistent.

The function terminates when it has successfully walked the entire heap or when it has found an error such as a bad cell pointer, a bad cell length or a cell which appears to overlap another cell.

Return value

TInt The value last set by the SetValue() function. See the SetValue() and the Value() functions.

virtual void Info(TCellType aType,TAny* aBase,TInt aLength)=0;

Description

Gets information for every good allocated cell and every good free cell on the heap together with the address and length of these cells. This function is called by the Walk() function.

It is also called when Walk() detects a free cell or an allocated cell which it considers to be bad. In this event, this is the last call to Info() before Walk() itself terminates.

Parameters

TCellType aType A description of the cell. If this is one of: EBadFreeCellAddress, EBadAllocatedCellSize or EBadAllocatedCellAddress, then this is the last call to this function. TAny* aBase A pointer to the cell; this may be an allocated cell or a free cell depending on the value of aType. TInt aLength The length of the cell.

protected: TInt Value() const;

Description

Returns the value currently held by this object. The class contains a private data member for holding this.

The heap walker function Walk() returns the current value when it terminates, either after successfully walking the entire heap or prematurely when it discovers a bad allocated or free cell.

The value can be set using the SetValue() member function.

No specific meaning is assigned to this value by this class; a derived class is free to use it as it wishes, for example, to keep a count of the number of cells found. It is likely that this function will be useful to the derived class implementation of Info().

Return value

TInt The value currently held by this object.

protected: void SetValue(TInt aValue);

Description

Sets a value into this object. The class contains a private data member for holding this value.

The heap walker function Walk() returns the current value when it terminates, either after successfully walking the entire heap or prematurely when it discovers a bad allocated or free cell.

No specific meaning is assigned to this value by this class; a derived class is free to use it as it wishes, for example, to keep a count of the number of cells found. It is likely that this function will be useful to the derived class implementation of Info().

Parameters

TInt aValue The value to be set into this object.

TCellType

Description

Describes the type and state of cell found on the heap by Walk(). Information of this type is passed to each call of the Info() function by the heap walker, Walk().

EGoodAllocatedCell The cell is an allocated cell. EGoodFreeCell The cell is a free cell. EBadAllocatedCellSize The cell is an allocated cell and its length is incorrect. EBadAllocatedCellAddress The cell is an allocated cell and its address is bad. EBadFreeCellAddress The cell is a free cell and its address is bad.