From Free Pascal wiki
Jump to: navigation, search

heaptrc is a unit that can be used to debug allocation and deallocation of memory blocks. It keeps track of calls to getmem/freemem, and, implicitly, of New/Dispose statements.

When a program using heaptrc ends, heaptrc can write out the total memory used and a list of allocated but not freed blocks to a file. When run in the console (*nix or Windows), heaptrc will print this output to screen unless otherwise instructed. In Lazarus GUI programs on Windows, the output will appear in numerous small dialog boxes, which may be very unpractical.

Standard output of heaptrc on Windows (despite of the title there is no error in the application)

On *nix (including BSD, Linux and Mac OS X), by default, nothing will be shown for GUI programs. See leakview for details on how to make use of heaptrc effectively.



Note: Do not add the heaptrc unit manually. The heaptrc unit needs to be loaded before lineinfo and only the compiler can do that.

Add a parameter -gh to your compilation command line or to fpc.cfg

fpc -gh helloworld.pas

This will add heaptrc implicitly as a hidden first unit of the program's uses clause.

You can test in code if heaptrc is active by examining the global variable UseHeapTrace for the presence of heaptrc and its status like so:

program testforheaptrace;
{$if declared(UseHeapTrace)}
   writeln('Heaptrc is used.',' Heaptrc is active? ', UseHeaptrace)  // heaptrc reports can be turned off when linked in... so true or false
   // you can subsequently test or set any of the heaptrc reporting options here.
   writeln('No trace of heaptrc');

Using heaptrc in Lazarus

To enable this in your Lazarus project: go to Project Options/Linking and in the Debugging section enable Use Heaptrc unit (check for mem-leaks) (-gh)

You can test for the presence of heaptrc in a similar manner as in the above example by testing for the presence of UseHeapTrace in your project.lpr file.

{$if declared(UseHeapTrace)}
//... do something
// test if active
if UseHeapTrace then ....// Test if reporting is on

Show report only on leak

If you want to show heaptrc report dialog only if there were leaks in your application, then put this command somewhere in your main project source file:

  {$if declared(UseHeapTrace)}
  GlobalSkipIfNoLeaks := true; // supported as of debugger version 3.1.1

Programmatically disable report

If you want to disable report from your code then you can directly manipulate UseHeapTrace variable at program startup

  UseHeapTrace := false;

Continue execution even on heap error

If you want you application to continue execution even in case of a heap error then manipulate HaltOnError variable at program startup

  HaltOnError := false;

Redirect report to file

If you want to redirect leak report to file then add this to beginning of you main project file:

  SetHeapTraceOutput('trace.log'); // supported as of debugger version 3.1.1

Why heaptrc should not be added to the uses clause manually

You should never add heaptrc manually in a normal program, because the heaptrc unit needs to be loaded before lineinfo for debugging to work properly.

Decoding dwarf debugging info efficiently requires a working heap manager and this means that heaptrc needs to be loaded before the the dwarf line info decoding unit which is loaded by -gl, so heaptrc cannot be used explicitly.

Only the compiler itself can insert the unit in its proper place as a hidden first unit in the uses clause. Adding the unit by hand can cause all kind of unwanted side effects. E.g. crashes, reported lineinfo is not reliable and not all leaks can reliably be reported.

This has always been the case, but is only properly documented from FPC version 3.0.2. So if you still see heaptrc in your uses clause, remove it! for debugging and reporting to work properly.

See also