You can heap-check any program that has the tcmalloc library linked in. No recompilation is necessary to use the heap checker.
In order to catch all heap leaks, tcmalloc must be linked last into your executable. The heap checker may mischaracterize some memory accesses in libraries listed after it on the link line. For instance, it may report these libraries as leaking memory when they're not. (See the source code for more details.)
It's safe to link in tcmalloc even if you don't expect to heap-check your program. Your programs will not run any slower as long as you don't use any of the heap-checker features.
You can run the heap checker on applications you didn't compile yourself, by using LD_PRELOAD:
$ LD_PRELOAD="/usr/lib/libtcmalloc.so" HEAPCHECK=normal
We don't necessarily recommend this mode of usage.
There are two alternatives to actually turn on heap checking for a given run of an executable.
$ HEAPCHECK=normal /bin/ls % setenv HEAPCHECK normal; /bin/ls # cshOR
HeapLeakCheckerobject (which takes a descriptive label as an argument), and calling
check.NoLeaks()at the end of the code you want checked. This will verify no more memory is allocated at the end of the code segment than was allocated in the beginning. To actually turn on the heap-checking, set the environment variable HEAPCHECK to
Here is an example of the second usage. The following code will
Foo() leaks any memory
(i.e. it allocates memory that is not freed by the time it returns):
HeapProfileLeakChecker checker("foo"); Foo(); assert(checker.NoLeaks());
checker object is allocated, it creates
one heap profile. When
checker.NoLeaks() is invoked,
it creates another heap profile and compares it to the previously
created profile. If the new profile indicates memory growth
(or any memory allocation change if one
will return false and the program will abort. An error message will
also be printed out saying how
pprof command can be run
to get a detailed analysis of the actual leaks.
See the comments for
HeapProfileLeakChecker class in
heap-checker.h and the code in
heap-checker_unittest.cc for more information and
examples. (TODO: document it all here instead!)
IMPORTANT NOTE: pthreads handling is currently incomplete. Heap leak checks will fail with bogus leaks if there are pthreads live at construction or leak checking time. One solution, for global heap-checking, is to make sure all threads but the main thread have exited at program-end time. We hope (as of March 2005) to have a fix soon.
Sometimes your code has leaks that you know about and are willing to accept. You would like the heap checker to ignore them when checking your program. You can do this by bracketing the code in question with an appropriate heap-checking object:
... void *mark = HeapLeakChecker::GetDisableChecksStart(); <leaky code> HeapLeakChecker::DisableChecksToHereFrom(mark);
Some libc routines allocate memory, and may need to be 'disabled' in this way. As time goes on, we hope to encode proper handling of these routines into the heap-checker library code, so applications needn't worry about them, but that process is not yet complete.