gc-7.2/doc/leak.html

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