heaptrc unit

This document describes the HEAPTRC unit for Free Pascal. It was written by Pierre Muller. It is system independent, and works on all supported systems.

The HEAPTRC unit can be used to debug your memory allocation/deallocation. It keeps track of the calls to getmem/freemem, and, implicitly, of New/Dispose statements.

When the program exits, or when you request it explicitly. It displays the total memory used, and then dumps a list of blocks that were allocated but not freed. It also displays where the memory was allocated.

If there are any inconsistencies, such as memory blocks being allocated or freed twice, or a memory block that is released but with wrong size, this will be displayed also.

The information that is stored/displayed can be customized using some constants.

Do not use this unit directly, instead use the -gh switch, to let the compiler insert the unit in the uses clause. You can detect whether the heaptrc unit is actually used in the main program code with the following function:

function IsHeapTraceActive : boolean;

begin
{$if declared(UseHeapTrace)}
  Result:=UseHeapTrace;
{$else}
  Result:=False;
{$endif}
end;

Classes and records

TWalkBlockInfo

record

Procedures and functions

CheckHeap	procedure
CheckPointer	procedure	Check if a pointer is in the address range of the application.
DumpHeap	procedure	Dump memory usage report to stderr.
GetHeadSize	function
GetKeepReleased	function
GetKeepReleasedBytes	function
GetKeepReleasedPercents	function
GetTailSize	function
GetTraceDepth	function
HexDump	procedure
SetHeadSize	procedure
SetHeapExtraInfo	procedure	Store extra information in blocks.
SetHeapTraceOutput	procedure	Specify filename or text file for heap trace output.
SetKeepReleased	procedure
SetKeepReleasedBytes	procedure
SetKeepReleasedPercents	procedure
SetTailSize	procedure
SetTraceDepth	procedure
WalkHeap	procedure

Types

head_size	property
KeepReleased	property	Keep released blocks in memory.
KeepReleasedBytes	property
KeepReleasedPercents	property
tail_size	property	Size of memory tail.
TDisplayExtraInfoProc	procedure type	The TDisplayExtraInfoProc is a procedural type used in the call.
TFillExtraInfoProc	procedure type	The FillExtraInfoProc is a procedural type used in the call.
TraceDepth	property
TWalkBlockProc	procedure type

Constants

AutoCheckHeapStep	constant
GlobalSkipIfNoLeaks	constant	Disable output if no leaks detected.
HaltOnError	constant	Halt program on memory fault.
HaltOnNotReleased	constant	Halt on exit if any memory was not freed.
IncludeInternalAllocationsInStatistics	constant
MaxLeaksToReport	constant
MaxPrintedBlockLength	constant	Maximum length of memory block dumps.
PrintFaultyBlock	constant	Print memory dump of faulty blocks ?
PrintLeakedBlock	constant	Print memory dump of leaked blocks ?
UseHeapTrace	constant	If set to False, the heap trace will be disabled.

Topics

environment	topic	Controlling HeapTrc with environment variables.
usage	topic	HeapTrc Usage.