Debian Codegraph @

external/bdwgc/doc/leak.md

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