Difference between revisions of "heaptrc"

From Lazarus wiki
Jump to navigationJump to search
Line 16: Line 16:
 
  fpc -gh helloworld.pas
 
  fpc -gh helloworld.pas
  
This will add heaptrc implicitly as the first unit of uses clause.
+
This will add heaptrc implicitly as the first unit of uses clause.<br>
Do not add the heaptrc unit by hand.<br>
+
'''Do not add the heaptrc unit manually.'''<br>
 
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:
 
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:
 
<syntaxhighlight>
 
<syntaxhighlight>

Revision as of 12:39, 14 February 2017

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.

Usage

Add a parameter -gh to your compilation command line

fpc -gh helloworld.pas

This will add heaptrc implicitly as the first unit of uses clause.
Do not add the heaptrc unit manually.
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;
begin
{$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 reporting options here.
{$else}
   writeln('No trace of heaptrc');
{$ifend}
end.


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 = true then ....// Test if reporting is on
{$ifend}

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:

  GlobalSkipIfNoLeaks := true;

Programatically 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');

Warning

(This information is deprecated as per version 3.0.2. Never add heaptrc by hand)
Don't put heaptrc into uses section more than one time. It's preferred if you never put into a unit uses section, but only into program uses section.


by avra on Lazarus forum

I would like to share my example of wrong heaptrc usage...

After some hard debugging and troubleshooting I wanted to dig a little into heaptrc unit to see if there was anything 
more inside of it which I  could have used along with TLogger. Therefore besides being the first unit in project, 
I have included it in one of my other units where I temporarily needed it.

What a wrong move!!!  >:(  :'( %)

In meantime I have solved my problem but completely forgotten to remove heaptrc from the uses in that other unit. 
Well, many, many man hours later   I have figured out why my application had sudden leaks, hangs and freezes, 
and totally different errors with heaptrc used or not with a project.  What a relief!

I wish IDE had at least warned me that I had heaptrc which was not the first used unit in a project, or that I had 2 such units.

Doc says only that it should be the first used unit in a project, but nothing said that it was dangerous to include it once more.

Cheers!

See also