| 1 |
721 |
jeremybenn |
<HTML>
|
| 2 |
|
|
<HEAD>
|
| 3 |
|
|
<TITLE>Using the Garbage Collector: A simple example</title>
|
| 4 |
|
|
</head>
|
| 5 |
|
|
<BODY>
|
| 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
|
| 15 |
|
|
<PRE>
|
| 16 |
|
|
tar xvfz gc<version>.tar.gz
|
| 17 |
|
|
cd gc<version>
|
| 18 |
|
|
</pre>
|
| 19 |
|
|
<P>
|
| 20 |
|
|
You can configure, build, and install the collector in a private
|
| 21 |
|
|
directory, say /home/xyz/gc, with the following commands:
|
| 22 |
|
|
<PRE>
|
| 23 |
|
|
./configure --prefix=/home/xyz/gc --disable-threads
|
| 24 |
|
|
make
|
| 25 |
|
|
make check
|
| 26 |
|
|
make install
|
| 27 |
|
|
</pre>
|
| 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.
|
| 30 |
|
|
<FONT COLOR=green>
|
| 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
|
| 38 |
|
|
place.
|
| 39 |
|
|
<P>
|
| 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
|
| 42 |
|
|
documented there.
|
| 43 |
|
|
<P>
|
| 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.)
|
| 47 |
|
|
<H3>Threads</h3>
|
| 48 |
|
|
If you need thread support, configure the collector with
|
| 49 |
|
|
<PRE>
|
| 50 |
|
|
--enable-threads=posix --enable-thread-local-alloc --enable-parallel-mark
|
| 51 |
|
|
</pre>
|
| 52 |
|
|
instead of
|
| 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>.
|
| 56 |
|
|
<H3>C++</h3>
|
| 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.
|
| 61 |
|
|
</font>
|
| 62 |
|
|
<H2>Writing the program</h2>
|
| 63 |
|
|
You will need a
|
| 64 |
|
|
<PRE>
|
| 65 |
|
|
#include "gc.h"
|
| 66 |
|
|
</pre>
|
| 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
|
| 71 |
|
|
result.
|
| 72 |
|
|
<P>
|
| 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.
|
| 76 |
|
|
<P>
|
| 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.
|
| 80 |
|
|
<P>
|
| 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.
|
| 84 |
|
|
<P>
|
| 85 |
|
|
The following program <TT>loop.c</tt> is a trivial example:
|
| 86 |
|
|
<PRE>
|
| 87 |
|
|
#include "gc.h"
|
| 88 |
|
|
#include <assert.h>
|
| 89 |
|
|
#include <stdio.h>
|
| 90 |
|
|
|
| 91 |
|
|
int main()
|
| 92 |
|
|
{
|
| 93 |
|
|
int i;
|
| 94 |
|
|
|
| 95 |
|
|
GC_INIT(); /* Optional on Linux/X86; see below. */
|
| 96 |
|
|
for (i = 0; i < 10000000; ++i)
|
| 97 |
|
|
{
|
| 98 |
|
|
int **p = (int **) GC_MALLOC(sizeof(int *));
|
| 99 |
|
|
int *q = (int *) GC_MALLOC_ATOMIC(sizeof(int));
|
| 100 |
|
|
assert(*p == 0);
|
| 101 |
|
|
*p = (int *) GC_REALLOC(q, 2 * sizeof(int));
|
| 102 |
|
|
if (i % 100000 == 0)
|
| 103 |
|
|
printf("Heap size = %d\n", GC_get_heap_size());
|
| 104 |
|
|
}
|
| 105 |
|
|
return 0;
|
| 106 |
|
|
}
|
| 107 |
|
|
</pre>
|
| 108 |
|
|
<FONT COLOR=green>
|
| 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
|
| 113 |
|
|
<TT>malloc</tt>.
|
| 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.
|
| 118 |
|
|
|
| 119 |
|
|
<H3>Threads</h3>
|
| 120 |
|
|
For a multithreaded program some more rules apply:
|
| 121 |
|
|
<UL>
|
| 122 |
|
|
<LI>
|
| 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.
|
| 127 |
|
|
<LI>
|
| 128 |
|
|
To take advantage of fast thread-local allocation, use the following instead
|
| 129 |
|
|
of including <TT>gc.h</tt>:
|
| 130 |
|
|
<PRE>
|
| 131 |
|
|
#define GC_REDIRECT_TO_LOCAL
|
| 132 |
|
|
#include "gc_local_alloc.h"
|
| 133 |
|
|
</pre>
|
| 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.
|
| 136 |
|
|
</ul>
|
| 137 |
|
|
|
| 138 |
|
|
<H3>C++</h3>
|
| 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>
|
| 142 |
|
|
to make that easier.
|
| 143 |
|
|
|
| 144 |
|
|
<H3>Debugging</h3>
|
| 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.
|
| 149 |
|
|
|
| 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.
|
| 156 |
|
|
|
| 157 |
|
|
</font>
|
| 158 |
|
|
|
| 159 |
|
|
<H2>Compiling and linking</h2>
|
| 160 |
|
|
|
| 161 |
|
|
The above application <TT>loop.c</tt> test program can be compiled and linked
|
| 162 |
|
|
with
|
| 163 |
|
|
|
| 164 |
|
|
<PRE>
|
| 165 |
|
|
cc -I/home/xyz/gc/include loop.c /home/xyz/gc/lib/libgc.a -o loop
|
| 166 |
|
|
</pre>
|
| 167 |
|
|
|
| 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>.
|
| 173 |
|
|
|
| 174 |
|
|
<FONT COLOR=green>
|
| 175 |
|
|
|
| 176 |
|
|
<H3>Threads</h3>
|
| 177 |
|
|
|
| 178 |
|
|
On pthread platforms, you will of course also have to link with
|
| 179 |
|
|
<TT>-lpthread</tt>,
|
| 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>
|
| 182 |
|
|
or <TT>-lrt</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.
|
| 186 |
|
|
|
| 187 |
|
|
</font>
|
| 188 |
|
|
|
| 189 |
|
|
<H2>Running the executable</h2>
|
| 190 |
|
|
|
| 191 |
|
|
The executable can of course be run normally, e.g. by typing
|
| 192 |
|
|
|
| 193 |
|
|
<PRE>
|
| 194 |
|
|
./loop
|
| 195 |
|
|
</pre>
|
| 196 |
|
|
|
| 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.
|
| 201 |
|
|
</body>
|
| 202 |
|
|
</html>
|
