3
<TITLE>Using the Garbage Collector: A simple example</title>
6
<H1>Using the Garbage Collector: A simple example</h1>
7
The following consists of step-by-step instructions for building and
8
using the collector. We'll assume a Linux/gcc platform and
9
a single-threaded application. <FONT COLOR=green>The green
10
text contains information about other platforms or scenarios.
11
It can be skipped, especially on first reading</font>.
12
<H2>Building the collector</h2>
13
If you haven't already so, unpack the collector and enter
14
the newly created directory with
16
tar xvfz gc<version>.tar.gz
20
You can configure, build, and install the collector in a private
21
directory, say /home/xyz/gc, with the following commands:
23
./configure --prefix=/home/xyz/gc --disable-threads
28
Here the "<TT>make check</tt>" command is optional, but highly recommended.
29
It runs a basic correctness test which usually takes well under a minute.
31
<H3>Other platforms</h3>
32
On non-Unix, non-Linux platforms, the collector is usually built by copying
33
the appropriate makefile (see the platform-specific README in doc/README.xxx
34
in the distribution) to the file "Makefile" (overwriting the copy of
35
Makefile.direct that was originally there), and then typing "make"
36
(or "nmake" or ...). This builds the library in the source tree. You may
37
want to move it and the files in the include directory to a more convenient
40
If you use a makefile that does not require running a configure script,
41
you should first look at the makefile, and adjust any options that are
44
If your platform provides a "make" utility, that is generally preferred
45
to platform- and compiler- dependent "project" files. (At least that is the
46
strong preference of the would-be maintainer of those project files.)
48
If you need thread support, configure the collector with
50
--enable-threads=posix --enable-thread-local-alloc --enable-parallel-mark
53
<TT>--disable-threads</tt>
54
If your target is a real old-fashioned uniprocessor (no "hyperthreading",
55
etc.) you will want to omit <TT>--enable-parallel-mark</tt>.
57
You will need to include the C++ support, which unfortunately tends to
58
be among the least portable parts of the collector, since it seems
59
to rely on some corner cases of the language. On Linux, it
60
suffices to add <TT>--enable-cplusplus</tt> to the configure options.
62
<H2>Writing the program</h2>
67
at the beginning of every file that allocates memory through the
68
garbage collector. Call <TT>GC_MALLOC</tt> wherever you would
69
have call <TT>malloc</tt>. This initializes memory to zero like
70
<TT>calloc</tt>; there is no need to explicitly clear the
73
If you know that an object will not contain pointers to the
74
garbage-collected heap, and you don't need it to be initialized,
75
call <TT>GC_MALLOC_ATOMIC</tt> instead.
77
A function <TT>GC_FREE</tt> is provided but need not be called.
78
For very small objects, your program will probably perform better if
79
you do not call it, and let the collector do its job.
81
A <TT>GC_REALLOC</tt> function behaves like the C library <TT>realloc</tt>.
82
It allocates uninitialized pointer-free memory if the original
83
object was allocated that way.
85
The following program <TT>loop.c</tt> is a trivial example:
88
#include <assert.h>
89
#include <stdio.h>
95
GC_INIT(); /* Optional on Linux/X86; see below. */
96
for (i = 0; i < 10000000; ++i)
98
int **p = (int **) GC_MALLOC(sizeof(int *));
99
int *q = (int *) GC_MALLOC_ATOMIC(sizeof(int));
101
*p = (int *) GC_REALLOC(q, 2 * sizeof(int));
103
printf("Heap size = %d\n", GC_get_heap_size());
109
<H3>Interaction with the system malloc</h3>
110
It is usually best not to mix garbage-collected allocation with the system
111
<TT>malloc-free</tt>. If you do, you need to be careful not to store
112
pointers to the garbage-collected heap in memory allocated with the system
114
<H3>Other Platforms</h3>
115
On some other platforms it is necessary to call <TT>GC_INIT()</tt> from the main program,
116
which is presumed to be part of the main executable, not a dynamic library.
117
This can never hurt, and is thus generally good practice.
120
For a multithreaded program some more rules apply:
123
Files that either allocate through the GC <I>or make thread-related calls</i>
124
should first define the macro <TT>GC_THREADS</tt>, and then
125
include <TT>"gc.h"</tt>. On some platforms this will redefine some
126
threads primitives, e.g. to let the collector keep track of thread creation.
128
To take advantage of fast thread-local allocation, use the following instead
129
of including <TT>gc.h</tt>:
131
#define GC_REDIRECT_TO_LOCAL
132
#include "gc_local_alloc.h"
134
This will cause GC_MALLOC and GC_MALLOC_ATOMIC to keep per-thread allocation
135
caches, and greatly reduce the number of lock acquisitions during allocation.
139
In the case of C++, you need to be especially careful not to store pointers
140
to the garbage-collected heap in areas that are not traced by the collector.
141
The collector includes some <A HREF="gcinterface.html">alternate interfaces</a>
145
Additional debug checks can be performed by defining <TT>GC_DEBUG</tt> before
146
including <TT>gc.h</tt>. Additional options are available if the collector
147
is also built with <TT>--enable-full_debug</tt> and all allocations are
148
performed with <TT>GC_DEBUG</tt> defined.
150
<H3>What if I can't rewrite/recompile my program?</h3>
151
You may be able to build the collector with <TT>--enable-redirect-malloc</tt>
152
and set the <TT>LD_PRELOAD</tt> environment variable to point to the resulting
153
library, thus replacing the standard <TT>malloc</tt> with its garbage-collected
154
counterpart. This is rather platform dependent. See the
155
<A HREF="leak.html">leak detection documentation</a> for some more details.
159
<H2>Compiling and linking</h2>
161
The above application <TT>loop.c</tt> test program can be compiled and linked
165
cc -I/home/xyz/gc/include loop.c /home/xyz/gc/lib/libgc.a -o loop
168
The <TT>-I</tt> option directs the compiler to the right include
169
directory. In this case, we list the static library
170
directly on the compile line; the dynamic library could have been
171
used instead, provided we arranged for the dynamic loader to find
172
it, e.g. by setting <TT>LD_LIBRARY_PATH</tt>.
178
On pthread platforms, you will of course also have to link with
180
and compile with any thread-safety options required by your compiler.
181
On some platforms, you may also need to link with <TT>-ldl</tt>
183
Looking at threadlibs.c in the GC build directory
184
should give you the appropriate
185
list if a plain <TT>-lpthread</tt> doesn't work.
189
<H2>Running the executable</h2>
191
The executable can of course be run normally, e.g. by typing
197
The operation of the collector is affected by a number of environment variables.
198
For example, setting <TT>GC_PRINT_STATS</tt> produces some
199
GC statistics on stdout.
200
See <TT>README.environment</tt> in the distribution for details.
added
removed
jam_src/boehm_gc/doc/simple_example.html
