Detecting Memory Leaks Using HeapTrc

"Memory leak" means that you allocated a memory for something, but didn’t deallocate it.

For example you created an instance of a class by MyInstance := TObject.Create but then forgot to call FreAndNil(MyInstance). See freeing classes (modern Pascal introduction). While Pascal offers various helpers to make it easy to deal with (e.g. TComponent can own other TComponent instances, freeing them automatically) but in general Pascal remains a language where you have to manually free all your allocated memory.

While not all memory leaks result in severe consequences, they usually indicate unsafe code organization and may be result of more extensive bugs. Therefore it is highly recommended to keep the code clean of memory leaks. This is where a very useful Free Pascal unit HeapTrc can help by enabling developers to debug run-time memory allocation and deallocation.

Using HeapTrc with Castle Game Engine is the same as with any other FPC application:

There are various ways to pass these options to FPC:

By default, HeapTrc will monitor all memory allocation and deallocation events during the program execution and will provide a thorough report after the execution stops in a regular way or due to an exception, unless the application process was killed by OS.

In effect, at the program’s exit, you will get a useful report about the allocated and not freed memory blocks (i.e. memory leaks). Each leak will have a stack trace to the allocation call. This allows to easily detect and fix memory leaks.

If everything is OK, the output looks like this:

But when you have a memory leak, it tells you about it, and tells you where the relevant memory was allocated, like this:

When you exit with Halt, ou will always have some memory leaks, that’s unavoidable right now. You should ignore the "Heap dump by heaptrc unit" output in this case.

Same thing applies when your program crashes with an unhandled exception.

The behavior in case of memory leaks on Windows GUI application is unfriendly. Memory leaks are displayed using a series of Windows modal message boxes, and you have to click through them, or kill the application.

It’s better to switch application to CONSOLE` for debugging, and run it from command-line, to observe HeapTrc output.

Or use the advise below to redirect the output to file.

By default, HeapTrc output is dumped into standard output (on *Nix systems and on console Windows applications). However, for Windows GUI applications, the HeapTrc output is shown as a series of modal popup windows and can be very tedious to work with in case the output is extensive.

This behavior can be changed by explicitly requesting to dump HeapTrc output to a file by using SetHeapTraceOutput procedure. E.g. add SetHeapTraceOutput(URLToFilenameSafe(ApplicationConfig('heaptrc.log'))); in main project source file.

Note, that as this way the HeapTrc would not be shown explicitly after the program exits, the developer has to remember to analyze this file manually to check if there are any memory leaks.