Debian Codegraph @

gc/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 is 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 The garbage collector provides leak detection support. This includes the
20 following features:
21
22 1. Leak detection mode can be initiated at run-time by `GC_set_find_leak(1)`
23 call at program startup instead of building the collector with `FIND_LEAK`
24 macro defined.
25 2. Leaked objects should be reported and then correctly garbage collected.
26
27 To use the collector as a leak detector, do the following steps:
28
29 1. Activate the leak detection mode as described above.
30 2. Change the program so that all allocation and deallocation goes through
31 the garbage collector.
32 3. Arrange to call `GC_gcollect` (or `CHECK_LEAKS()`) at appropriate points
33 to check for leaks. (This happens implicitly but probably not with
34 a sufficient frequency for long running programs.)
35
36 The second step can usually be accomplished with the
37 `-DREDIRECT_MALLOC=GC_malloc` option when the collector is built, or by
38 defining `malloc`, `calloc`, `realloc`, `free` (as well as `strdup`,
39 `strndup`, `wcsdup`, `memalign`, `posix_memalign`) to call the corresponding
40 garbage collector functions. But this, by itself, will not yield very
41 informative diagnostics, since the collector does not keep track of the
42 information about how objects were allocated. The error reports will include
43 only object addresses.
44
45 For more precise error reports, as much of the program as possible should use
46 the all uppercase variants of these functions, after defining `GC_DEBUG`, and
47 then including `gc.h`. In this environment `GC_MALLOC` is a macro which causes
48 at least the file name and line number at the allocation point to be saved
49 as part of the object. Leak reports will then also include this information.
50
51 Many collector features (e.g. finalization and disappearing links) are less
52 useful in this context, and are not fully supported. Their use will usually
53 generate additional bogus leak reports, since the collector itself drops some
54 associated objects.
55
56 The same is generally true of thread support. However, the correct leak
57 reports should be generated with linuxthreads, at least.
58
59 On a few platforms (currently Solaris/SPARC, Irix, and, with
60 `-DSAVE_CALL_CHAIN`, Linux/x86), `GC_MALLOC` also causes some more information
61 about its call stack to be saved in the object. Such information is reproduced
62 in the error reports in very non-symbolic form, but it can be very useful with
63 the aid of a debugger.
64
65 ## An Example
66
67 The `leak_detector.h` file is included in the "include" subdirectory of the
68 distribution.
69
70 Assume the collector has been built with `-DFIND_LEAK` or
71 `GC_set_find_leak(1)` exists as the first statement in `main`.
72
73 The program to be tested for leaks could look like `tests/leak_test.c` file
74 of the distribution.
75
76 On a Linux/x86 system this produces on the stderr stream:
77
78
79 Found 1 leaked objects:
80 0x806dff0 (tests/leak_test.c:19, sz=4, NORMAL)
81
82
83 (On most unmentioned operating systems, the output is similar to this. If the
84 collector had been built on Linux/x86 with `-DSAVE_CALL_CHAIN`, the output
85 would be closer to the Solaris example. For this to work, the program should
86 not be compiled with `-fomit_frame_pointer`.)
87
88 On Irix it reports:
89
90
91 Found 1 leaked objects:
92 0x10040fe0 (tests/leak_test.c:19, sz=4, NORMAL)
93 Caller at allocation:
94 ##PC##= 0x10004910
95
96
97 and on Solaris the error report is:
98
99
100 Found 1 leaked objects:
101 0xef621fc8 (tests/leak_test.c:19, sz=4, NORMAL)
102 Call chain at allocation:
103 args: 4 (0x4), 200656 (0x30FD0)
104 ##PC##= 0x14ADC
105 args: 1 (0x1), -268436012 (0xEFFFFDD4)
106 ##PC##= 0x14A64
107
108
109 In the latter two cases some additional information is given about how malloc
110 was called when the leaked object was allocated. For Solaris, the first line
111 specifies the arguments to `GC_debug_malloc` (the actual allocation routine),
112 The second one specifies the program counter inside `main`, the third one
113 specifies the arguments to `main`, and, finally, the program counter inside
114 the caller to `main` (i.e. in the C startup code). In the Irix case, only the
115 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. The collector
120 tries to generate symbolic names for call stacks if it knows how to do so on
121 the platform. This is true on Linux/x86, but not on most other platforms.
122
123 ## Simplified leak detection under Linux
124
125 It should be possible to run the collector in the leak detection mode on
126 a program a.out under Linux/x86 as follows:
127
128 1. If possible, ensure that a.out is a single-threaded executable. On some
129 platforms this does not work at all for the multi-threaded programs.
130 2. If possible, ensure that the `addr2line` program is installed
131 in `/usr/bin`. (It comes with most Linux distributions.)
132 3. If possible, compile your program, which we'll call `a.out`, with full
133 debug information. This will improve the quality of the leak reports.
134 With this approach, it is no longer necessary to call `GC_` routines
135 explicitly, though that can also improve the quality of the leak reports.
136 4. Build the collector and install it in directory _foo_ as follows (it may
137 be safe to omit the `--disable-threads` option on Linux, but the combination
138 of thread support and `malloc` replacement is not yet rock solid):
139
140 - `configure --prefix=_foo_ --enable-gc-debug --enable-redirect-malloc --disable-threads`
141 - `make`
142 - `make install`
143
144 5. Set environment variables as follows (the last two are optional, just to
145 confirm the collector is running, and to facilitate debugging from another
146 console window if something goes wrong, respectively):
147
148 - `LD_PRELOAD=_foo_/lib/libgc.so`
149 - `GC_FIND_LEAK`
150 - `GC_PRINT_STATS`
151 - `GC_LOOP_ON_ABORT`
152
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.
158
159 This has not yet been thoroughly tested on large applications, but it's known
160 to do the right thing on at least some small ones.