-<HTML>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html lang="en-us">
<HEAD>
+<meta http-equiv="Content-Type" content="text/html;charset=US-ASCII" >
<TITLE>Using the Garbage Collector as Leak Detector</title>
</head>
<BODY>
features:
<OL>
<LI> Leak detection mode can be initiated at run-time by
-setting GC_find_leak instead of building the collector with FIND_LEAK
+setting <TT>GC_find_leak</tt> instead of building the
+collector with <TT>FIND_LEAK</tt>
defined. This variable should be set to a nonzero value
at program startup.
<LI> Leaked objects should be reported and then correctly garbage collected.
<P>
To use the collector as a leak detector, follow the following steps:
<OL>
-<LI> Build the collector with -DFIND_LEAK. Otherwise use default
+<LI> Build the collector with <TT>-DFIND_LEAK</tt>. Otherwise use default
build options.
<LI> Change the program so that all allocation and deallocation goes
through the garbage collector.
#define CHECK_LEAKS() GC_gcollect()
</pre>
<P>
-Assume the collector has been built with -DFIND_LEAK. (For very
-new versions of the collector, we could instead add the statement
-<TT>GC_find_leak = 1</tt> as the first statement in <TT>main</tt>.
+Assume the collector has been built with <TT>-DFIND_LEAK</tt>. (For
+newer versions of the collector, we could instead add the statement
+<TT>GC_find_leak = 1</tt> as the first statement in <TT>main()</tt>.
<P>
The program to be tested for leaks can then look like:
<PRE>
int i;
/* GC_find_leak = 1; for new collector versions not */
/* compiled with -DFIND_LEAK. */
- for (i = 0; i < 10; ++i) {
+ for (i = 0; i < 10; ++i) {
p[i] = malloc(sizeof(int)+i);
}
- for (i = 1; i < 10; ++i) {
+ for (i = 1; i < 10; ++i) {
free(p[i]);
}
- for (i = 0; i < 9; ++i) {
+ for (i = 0; i < 9; ++i) {
p[i] = malloc(sizeof(int)+i);
}
CHECK_LEAKS();
a very recent (7.0alpha7+) collector version on Linux.</i>
On most platforms this does not
work at all for multithreaded programs.
-<LI> If possible, ensure that the addr2line program is installed in
-/usr/bin. (It comes with RedHat Linux.)
-<LI> If possible, compile a.out with full debug information.
+<LI> If possible, ensure that the <TT>addr2line</tt> program is installed in
+<TT>/usr/bin</tt>. (It comes with most Linux distributions.)
+<LI> If possible, compile your program, which we'll call <TT>a.out</tt>,
+with full debug information.
This will improve the quality of the leak reports. With this approach, it is
-no longer necessary to call GC_ routines explicitly, though that can also
+no longer necessary to call <TT>GC_</tt> routines explicitly,
+though that can also
improve the quality of the leak reports.
<LI> Build the collector and install it in directory <I>foo</i> as follows:
<UL>
-<LI> <TT>configure --prefix=<I>foo</i> --enable-full-debug --enable-redirect-malloc
+<LI> <TT>configure --prefix=<I>foo</i> --enable-gc-debug --enable-redirect-malloc
--disable-threads</tt>
<LI> <TT>make</tt>
<LI> <TT>make install</tt>
</ul>
-With a very recent collector on Linux, it may be safe to omit the <TT>--disable-threads</tt>.
+With a very recent collector on Linux, it may sometimes be safe to omit
+the <TT>--disable-threads</tt>. But the combination of thread support
+and <TT>malloc</tt> replacement is not yet rock solid.
<LI> Set environment variables as follows:
<UL>
-<LI> LD_PRELOAD=<I>foo</i>/lib/libgc.so
-<LI> GC_FIND_LEAK
-<LI> You may also want to set GC_PRINT_STATS (to confirm that the collector
-is running) and/or GC_LOOP_ON_ABORT (to facilitate debugging from another
+<LI> <TT>LD_PRELOAD=</tt><I>foo</i><TT>/lib/libgc.so</tt>
+<LI> <TT>GC_FIND_LEAK</tt>
+<LI> You may also want to set <TT>GC_PRINT_STATS</tt>
+(to confirm that the collector is running) and/or
+<TT>GC_LOOP_ON_ABORT</tt> (to facilitate debugging from another
window if something goes wrong).
-</ul
-<LI> Simply run a.out as you normally would. Note that if you run anything
+</ul>
+<LI> Simply run <TT>a.out</tt> as you normally would. Note that if you run anything
else (<I>e.g.</i> your editor) with those environment variables set,
it will also be leak tested. This may or may not be useful and/or
embarrassing. It can generate