boehm-gc/doc/leak.html

   1 <HTML>
   2 <HEAD>
   3 <TITLE>Using the Garbage Collector as Leak Detector</title>
   4 </head>
   5 <BODY>
   6 <H1>Using the Garbage Collector as Leak Detector</h1>
   7 The garbage collector may be used as a leak detector.
   8 In this case, the primary function of the collector is to report
   9 objects that were allocated (typically with <TT>GC_MALLOC</tt>),
  10 not deallocated (normally with <TT>GC_FREE</tt>), but are
  11 no longer accessible.  Since the object is no longer accessible,
  12 there in normally no way to deallocate the object at a later time;
  13 thus it can safely be assumed that the object has been "leaked".
  14 <P>
  15 This is substantially different from counting leak detectors,
  16 which simply verify that all allocated objects are eventually
  17 deallocated.  A garbage-collector based leak detector can provide
  18 somewhat more precise information when an object was leaked.
  19 More importantly, it does not report objects that are never
  20 deallocated because they are part of "permanent" data structures.
  21 Thus it does not require all objects to be deallocated at process
  22 exit time, a potentially useless activity that often triggers
  23 large amounts of paging.
  24 <P>
  25 All non-ancient versions of the garbage collector provide
  26 leak detection support.  Version 5.3 adds the following
  27 features:
  28 <OL>
  29 <LI> Leak detection mode can be initiated at run-time by
  30 setting GC_find_leak instead of building the collector with FIND_LEAK
  31 defined.  This variable should be set to a nonzero value
  32 at program startup.
  33 <LI> Leaked objects should be reported and then correctly garbage collected.
  34 Prior versions either reported leaks or functioned as a garbage collector.
  35 </ol>
  36 For the rest of this description we will give instructions that work
  37 with any reasonable version of the collector.
  38 <P>
  39 To use the collector as a leak detector, follow the following steps:
  40 <OL>
  41 <LI> Build the collector with -DFIND_LEAK.  Otherwise use default
  42 build options.
  43 <LI> Change the program so that all allocation and deallocation goes
  44 through the garbage collector.
  45 <LI> Arrange to call <TT>GC_gcollect</tt> at appropriate points to check
  46 for leaks.
  47 (For sufficiently long running programs, this will happen implicitly,
  48 but probably not with sufficient frequency.)
  49 </ol>
  50 The second step can usually be accomplished with the
  51 <TT>-DREDIRECT_MALLOC=GC_malloc</tt> option when the collector is built,
  52 or by defining <TT>malloc</tt>, <TT>calloc</tt>,
  53 <TT>realloc</tt> and <TT>free</tt>
  54 to call the corresponding garbage collector functions.
  55 But this, by itself, will not yield very informative diagnostics,
  56 since the collector does not keep track of information about
  57 how objects were allocated.  The error reports will include
  58 only object addresses.
  59 <P>
  60 For more precise error reports, as much of the program as possible
  61 should use the all uppercase variants of these functions, after
  62 defining <TT>GC_DEBUG</tt>, and then including <TT>gc.h</tt>.
  63 In this environment <TT>GC_MALLOC</tt> is a macro which causes
  64 at least the file name and line number at the allocation point to
  65 be saved as part of the object.  Leak reports will then also include
  66 this information.
  67 <P>
  68 Many collector features (<I>e.g</i> stubborn objects, finalization,
  69 and disappearing links) are less useful in this context, and are not
  70 fully supported.  Their use will usually generate additional bogus
  71 leak reports, since the collector itself drops some associated objects.
  72 <P>
  73 The same is generally true of thread support.  However, as of 6.0alpha4,
  74 correct leak reports should be generated with linuxthreads.
  75 <P>
  76 On a few platforms (currently Solaris/SPARC, Irix, and, with -DSAVE_CALL_CHAIN,
  77 Linux/X86), <TT>GC_MALLOC</tt>
  78 also causes some more information about its call stack to be saved
  79 in the object.  Such information is reproduced in the error
  80 reports in very non-symbolic form, but it can be very useful with the
  81 aid of a debugger.
  82 <H2>An Example</h2>
  83 The following header file <TT>leak_detector.h</tt> is included in the
  84 "include" subdirectory of the distribution:
  85 <PRE>
  86 #define GC_DEBUG
  87 #include "gc.h"
  88 #define malloc(n) GC_MALLOC(n)
  89 #define calloc(m,n) GC_MALLOC((m)*(n))
  90 #define free(p) GC_FREE(p)
  91 #define realloc(p,n) GC_REALLOC((p),(n))
  92 #define CHECK_LEAKS() GC_gcollect()
  93 </pre>
  94 <P>
  95 Assume the collector has been built with -DFIND_LEAK.  (For very
  96 new versions of the collector, we could instead add the statement
  97 <TT>GC_find_leak = 1</tt> as the first statement in <TT>main</tt>.
  98 <P>
  99 The program to be tested for leaks can then look like:
 100 <PRE>
 101 #include "leak_detector.h"
 102
 103 main() {
 104     int *p[10];
 105     int i;
 106     /* GC_find_leak = 1; for new collector versions not         */
 107     /* compiled with -DFIND_LEAK.                               */
 108     for (i = 0; i < 10; ++i) {
 109         p[i] = malloc(sizeof(int)+i);
 110     }
 111     for (i = 1; i < 10; ++i) {
 112         free(p[i]);
 113     }
 114     for (i = 0; i < 9; ++i) {
 115         p[i] = malloc(sizeof(int)+i);
 116     }
 117     CHECK_LEAKS();
 118 }
 119 </pre>
 120 <P>
 121 On an Intel X86 Linux system this produces on the stderr stream:
 122 <PRE>
 123 Leaked composite object at 0x806dff0 (leak_test.c:8, sz=4)
 124 </pre>
 125 (On most unmentioned operating systems, the output is similar to this.
 126 If the collector had been built on Linux/X86 with -DSAVE_CALL_CHAIN,
 127 the output would be closer to the Solaris example. For this to work,
 128 the program should not be compiled with -fomit_frame_pointer.)
 129 <P>
 130 On Irix it reports
 131 <PRE>
 132 Leaked composite object at 0x10040fe0 (leak_test.c:8, sz=4)
 133         Caller at allocation:
 134                 ##PC##= 0x10004910
 135 </pre>
 136 and on Solaris the error report is
 137 <PRE>
 138 Leaked composite object at 0xef621fc8 (leak_test.c:8, sz=4)
 139         Call chain at allocation:
 140                 args: 4 (0x4), 200656 (0x30FD0)
 141                 ##PC##= 0x14ADC
 142                 args: 1 (0x1), -268436012 (0xEFFFFDD4)
 143                 ##PC##= 0x14A64
 144 </pre>
 145 In the latter two cases some additional information is given about
 146 how malloc was called when the leaked object was allocated.  For
 147 Solaris, the first line specifies the arguments to <TT>GC_debug_malloc</tt>
 148 (the actual allocation routine), The second the program counter inside
 149 main, the third the arguments to <TT>main</tt>, and finally the program
 150 counter inside the caller to main (i.e. in the C startup code).
 151 <P>
 152 In the Irix case, only the address inside the caller to main is given.
 153 <P>
 154 In many cases, a debugger is needed to interpret the additional information.
 155 On systems supporting the "adb" debugger, the <TT>callprocs</tt> script
 156 can be used to replace program counter values with symbolic names.
 157 As of version 6.1, the collector tries to generate symbolic names for
 158 call stacks if it knows how to do so on the platform.  This is true on
 159 Linux/X86, but not on most other platforms.
 160 <H2>Simplified leak detection under Linux</h2>
 161 Since version 6.1, it should be possible to run the collector in leak
 162 detection mode on a program a.out under Linux/X86 as follows:
 163 <OL>
 164 <LI> Ensure that a.out is a single-threaded executable.  This doesn't yet work
 165 for multithreaded programs.
 166 <LI> If possible, ensure that the addr2line program is installed in
 167 /usr/bin.  (It comes with RedHat Linux.)
 168 <LI> If possible, compile a.out with full debug information.
 169 This will improve the quality of the leak reports.  With this approach, it is
 170 no longer necessary to call GC_ routines explicitly, though that can also
 171 improve the quality of the leak reports.
 172 <LI> Build the collector and install it in directory <I>foo</i> as follows:
 173 <UL>
 174 <LI> configure --prefix=<I>foo</i> --enable-full-debug --enable-redirect-malloc
 175 --disable-threads
 176 <LI> make
 177 <LI> make install
 178 </ul>
 179 <LI> Set environment variables as follows:
 180 <UL>
 181 <LI> LD_PRELOAD=<I>foo</i>/lib/libgc.so
 182 <LI> GC_FIND_LEAK
 183 <LI> You may also want to set GC_PRINT_STATS (to confirm that the collector
 184 is running) and/or GC_LOOP_ON_ABORT (to facilitate debugging from another
 185 window if something goes wrong).
 186 </ul
 187 <LI> Simply run a.out as you normally would.  Note that if you run anything
 188 else (<I>e.g.</i> your editor) with those environment variables set,
 189 it will also be leak tested.  This may or may not be useful and/or
 190 embarrassing.  It can generate
 191 mountains of leak reports if the application wasn't designed to avoid leaks,
 192 <I>e.g.</i> because it's always short-lived.
 193 </ol>
 194 This has not yet been thropughly tested on large applications, but it's known
 195 to do the right thing on at least some small ones.
 196 </body>
 197 </html>