|
51488
|
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>
|
