143 lines
4.6 KiB
HTML
143 lines
4.6 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>Google Heap Checker</title>
|
|
</head>
|
|
|
|
<body>
|
|
<h1>Automatic Leaks Checking Support</h1>
|
|
|
|
This document describes how to check the heap usage of a C++
|
|
program. This facility can be useful for automatically detecting
|
|
memory leaks.
|
|
|
|
<h2>Linking in the Heap Checker</h2>
|
|
|
|
<p>
|
|
You can heap-check any program that has the tcmalloc library linked
|
|
in. No recompilation is necessary to use the heap checker.
|
|
</p>
|
|
|
|
<p>
|
|
In order to catch all heap leaks, tcmalloc must be linked <i>last</i> 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.)
|
|
</p>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<p>
|
|
You can run the heap checker on applications you didn't compile
|
|
yourself, by using LD_PRELOAD:
|
|
</p>
|
|
<pre>
|
|
$ LD_PRELOAD="/usr/lib/libtcmalloc.so" HEAPCHECK=normal <binary>
|
|
</pre>
|
|
<p>
|
|
We don't necessarily recommend this mode of usage.
|
|
</p>
|
|
|
|
<h2>Turning On Heap Checking</h2>
|
|
|
|
<p>There are two alternatives to actually turn on heap checking for a
|
|
given run of an executable.</p>
|
|
|
|
<ul>
|
|
<li> For whole-program heap-checking, define the environment variable
|
|
HEAPCHECK to the type of heap
|
|
checking you want: normal, strict, or draconian. For instance,
|
|
to heap-check <code>/bin/ls</code>:
|
|
<pre>
|
|
$ HEAPCHECK=normal /bin/ls
|
|
% setenv HEAPCHECK normal; /bin/ls # csh
|
|
</pre>
|
|
OR
|
|
|
|
<li> For partial-code heap-checking, you need to modify your code.
|
|
For each piece of code you want heap-checked, bracket the code
|
|
by creating a <code>HeapLeakChecker</code> object
|
|
(which takes a descriptive label as an argument), and calling
|
|
<code>check.NoLeaks()</code> 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 <code>local</code>.
|
|
</ol>
|
|
|
|
<p>
|
|
Here is an example of the second usage. The following code will
|
|
die if <code>Foo()</code> leaks any memory
|
|
(i.e. it allocates memory that is not freed by the time it returns):
|
|
</p>
|
|
<pre>
|
|
HeapProfileLeakChecker checker("foo");
|
|
Foo();
|
|
assert(checker.NoLeaks());
|
|
</pre>
|
|
|
|
<p>
|
|
When the <code>checker</code> object is allocated, it creates
|
|
one heap profile. When <code>checker.NoLeaks()</code> 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
|
|
uses <code>checker.SameHeap()</code> instead), <code>NoLeaks()</code>
|
|
will return false and the program will abort. An error message will
|
|
also be printed out saying how <code>pprof</code> command can be run
|
|
to get a detailed analysis of the actual leaks.
|
|
</p>
|
|
|
|
<p>
|
|
See the comments for <code>HeapProfileLeakChecker</code> class in
|
|
<code>heap-checker.h</code> and the code in
|
|
<code>heap-checker_unittest.cc</code> for more information and
|
|
examples. (TODO: document it all here instead!)
|
|
</p>
|
|
|
|
<p>
|
|
<b>IMPORTANT NOTE</b>: 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.
|
|
</p>
|
|
|
|
<h2>Disabling Heap-checking of Known Leaks</h2>
|
|
|
|
<p>
|
|
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:
|
|
</p>
|
|
<pre>
|
|
#include <google/heap-checker.h>
|
|
...
|
|
void *mark = HeapLeakChecker::GetDisableChecksStart();
|
|
<leaky code>
|
|
HeapLeakChecker::DisableChecksToHereFrom(mark);
|
|
</pre>
|
|
|
|
<p>
|
|
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.
|
|
</p>
|
|
|
|
<hr>
|
|
<address><a href="mailto:opensource@google.com">Maxim Lifantsev</a></address>
|
|
<!-- Created: Tue Dec 19 10:43:14 PST 2000 -->
|
|
<!-- hhmts start -->
|
|
Last modified: Thu Mar 3 05:51:40 PST 2005
|
|
<!-- hhmts end -->
|
|
</body>
|
|
</html>
|