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