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