| 1 |
# Using the Garbage Collector: A simple example |
| 2 |
|
| 3 |
The following consists of step-by-step instructions for building and using the |
| 4 |
collector. We'll assume a Linux/gcc platform and a single-threaded |
| 5 |
application. The green text contains information about other platforms |
| 6 |
or scenarios. It can be skipped, especially on first reading. |
| 7 |
|
| 8 |
## Building the collector |
| 9 |
|
| 10 |
If you have not so yet, unpack the collector and enter the newly created |
| 11 |
directory with: |
| 12 |
|
| 13 |
|
| 14 |
tar xvfz gc-<version>.tar.gz |
| 15 |
cd gc-<version> |
| 16 |
|
| 17 |
|
| 18 |
You can configure, build, and install the collector in a private directory, |
| 19 |
say /home/xyz/gc, with the following commands: |
| 20 |
|
| 21 |
|
| 22 |
./configure --prefix=/home/xyz/gc --disable-threads |
| 23 |
make |
| 24 |
make check |
| 25 |
make install |
| 26 |
|
| 27 |
|
| 28 |
Here the `make check` command is optional, but highly recommended. It runs |
| 29 |
a basic correctness test which usually takes well under a minute. |
| 30 |
|
| 31 |
### Other platforms |
| 32 |
|
| 33 |
On non-Unix, non-Linux platforms, the collector is usually built by copying |
| 34 |
the appropriate makefile (see the platform-specific README in doc/README.xxx |
| 35 |
in the distribution) to the file "Makefile", and then typing `make` (or |
| 36 |
`nmake` or ...). This builds the library in the source tree. You may want |
| 37 |
to move it and the files in the include directory to a more convenient place. |
| 38 |
|
| 39 |
If you use a makefile that does not require running a configure script, you |
| 40 |
should first look at the makefile, and adjust any options that are documented |
| 41 |
there. |
| 42 |
|
| 43 |
If your platform provides a `make` utility, that is generally preferred |
| 44 |
to platform- and compiler- dependent "project" files. (At least that is the |
| 45 |
strong preference of the would-be maintainer of those project files.) |
| 46 |
|
| 47 |
### Threads |
| 48 |
|
| 49 |
If you do not need thread support, configure the collector with: |
| 50 |
|
| 51 |
|
| 52 |
--disable-threads |
| 53 |
|
| 54 |
|
| 55 |
Alternatively, if your target is a real old-fashioned uniprocessor (no |
| 56 |
"hyperthreading", etc.), you may just want to turn off parallel marking with |
| 57 |
`--disable-parallel-mark`. |
| 58 |
|
| 59 |
### C++ |
| 60 |
|
| 61 |
You will need to include the C++ support, which unfortunately tends to be |
| 62 |
among the least portable parts of the collector, since it seems to rely |
| 63 |
on some corner cases of the language. On Linux, it suffices to add |
| 64 |
`--enable-cplusplus` to the configure options. |
| 65 |
|
| 66 |
## Writing the program |
| 67 |
|
| 68 |
You will need to include "gc.h" at the beginning of every file that allocates |
| 69 |
memory through the garbage collector. Call `GC_MALLOC` wherever you would have |
| 70 |
call `malloc`. This initializes memory to zero like `calloc`; there is no need |
| 71 |
to explicitly clear the result. |
| 72 |
|
| 73 |
If you know that an object will not contain pointers to the garbage-collected |
| 74 |
heap, and you don't need it to be initialized, call `GC_MALLOC_ATOMIC` |
| 75 |
instead. |
| 76 |
|
| 77 |
A function `GC_FREE` is provided but need not be called. For very small |
| 78 |
objects, your program will probably perform better if you do not call it, and |
| 79 |
let the collector do its job. |
| 80 |
|
| 81 |
A `GC_REALLOC` function behaves like the C library `realloc`. It allocates |
| 82 |
uninitialized pointer-free memory if the original object was allocated that |
| 83 |
way. |
| 84 |
|
| 85 |
The following program `loop.c` is a trivial example: |
| 86 |
|
| 87 |
|
| 88 |
#include "gc.h" |
| 89 |
#include <assert.h> |
| 90 |
#include <stdio.h> |
| 91 |
|
| 92 |
int main(void) { |
| 93 |
int i; |
| 94 |
|
| 95 |
GC_INIT(); |
| 96 |
for (i = 0; i < 10000000; ++i) { |
| 97 |
int **p = (int **) GC_MALLOC(sizeof(int *)); |
| 98 |
int *q = (int *) GC_MALLOC_ATOMIC(sizeof(int)); |
| 99 |
assert(*p == 0); |
| 100 |
*p = (int *) GC_REALLOC(q, 2 * sizeof(int)); |
| 101 |
if (i % 100000 == 0) |
| 102 |
printf("Heap size = %lu bytes\n", |
| 103 |
(unsigned long)GC_get_heap_size()); |
| 104 |
} |
| 105 |
return 0; |
| 106 |
} |
| 107 |
|
| 108 |
|
| 109 |
### Interaction with the system malloc |
| 110 |
|
| 111 |
It is usually best not to mix garbage-collected allocation with the system |
| 112 |
`malloc`-`free`. If you do, you need to be careful not to store pointers |
| 113 |
to the garbage-collected heap in memory allocated with the system `malloc`. |
| 114 |
|
| 115 |
### Other Platforms |
| 116 |
|
| 117 |
On some other platforms it is necessary to call `GC_INIT` from the main |
| 118 |
program, which is presumed to be part of the main executable, not a dynamic |
| 119 |
library. This can never hurt, and is thus generally good practice. |
| 120 |
|
| 121 |
### Threads |
| 122 |
|
| 123 |
For a multi-threaded program, some more rules apply: |
| 124 |
|
| 125 |
* Files that either allocate through the GC _or make thread-related calls_ |
| 126 |
should first define the macro `GC_THREADS`, and then include `gc.h`. On some |
| 127 |
platforms this will redefine some threads primitives, e.g. to let the |
| 128 |
collector keep track of thread creation. |
| 129 |
|
| 130 |
### C++ |
| 131 |
|
| 132 |
In the case of C++, you need to be especially careful not to store pointers |
| 133 |
to the garbage-collected heap in areas that are not traced by the collector. |
| 134 |
The collector includes some _alternate interfaces_ to make that easier. |
| 135 |
|
| 136 |
### Debugging |
| 137 |
|
| 138 |
Additional debug checks can be performed by defining `GC_DEBUG` before |
| 139 |
including `gc.h`. Additional options are available if the collector is also |
| 140 |
built with `--enable-gc-debug` and all allocations are performed with |
| 141 |
`GC_DEBUG` defined. |
| 142 |
|
| 143 |
### What if I can't rewrite/recompile my program? |
| 144 |
|
| 145 |
You may be able to build the collector with `--enable-redirect-malloc` and set |
| 146 |
the `LD_PRELOAD` environment variable to point to the resulting library, thus |
| 147 |
replacing the standard `malloc` with its garbage-collected counterpart. This |
| 148 |
is rather platform dependent. See the _GC leak detection documentation_ for |
| 149 |
some more details. |
| 150 |
|
| 151 |
## Compiling and linking |
| 152 |
|
| 153 |
The above application `loop.c` test program can be compiled and linked with: |
| 154 |
|
| 155 |
|
| 156 |
cc -I/home/xyz/gc/include loop.c /home/xyz/gc/lib/libgc.a -o loop |
| 157 |
|
| 158 |
|
| 159 |
The `-I` option directs the compiler to the right include directory. In this |
| 160 |
case, we list the static library directly on the compile line; the dynamic |
| 161 |
library could have been used instead, provided we arranged for the dynamic |
| 162 |
loader to find it, e.g. by setting `LD_LIBRARY_PATH`. |
| 163 |
|
| 164 |
### Threads |
| 165 |
|
| 166 |
On pthread platforms, you will of course also have to link with `-lpthread`, |
| 167 |
and compile with any thread-safety options required by your compiler. On some |
| 168 |
platforms, you may also need to link with `-ldl` or `-lrt`. Looking |
| 169 |
at `tools/threadlibs.c` should give you the appropriate list if a plain |
| 170 |
`-lpthread` does not work. |
| 171 |
|
| 172 |
## Running the executable |
| 173 |
|
| 174 |
The executable can of course be run normally, e.g. by typing: |
| 175 |
|
| 176 |
|
| 177 |
./loop |
| 178 |
|
| 179 |
|
| 180 |
The operation of the collector is affected by a number of environment |
| 181 |
variables. For example, setting `GC_PRINT_STATS` produces some GC statistics |
| 182 |
on stdout. See `README.environment` in the distribution for details. |