source: trunk/gc6.8/doc/simple_example.html

Last change on this file was 132, checked in by cinc, 19 years ago

Boehm-Demers-Weiser garbage collector. Single-threaded for OS/2.
File size: 7.2 KB
Line 
1<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>
7The following consists of step-by-step instructions for building and
8using the collector. We'll assume a Linux/gcc platform and
9a single-threaded application. <FONT COLOR=green>The green
10text contains information about other platforms or scenarios.
11It can be skipped, especially on first reading</font>.
12<H2>Building the collector</h2>
13If you haven't already so, unpack the collector and enter
14the newly created directory with
15<PRE>
16tar xvfz gc<version>.tar.gz
17cd gc<version>
18</pre>
19<P>
20You can configure, build, and install the collector in a private
21directory, say /home/xyz/gc, with the following commands:
22<PRE>
23./configure --prefix=/home/xyz/gc --disable-threads
24make
25make check
26make install
27</pre>
28Here the "<TT>make check</tt>" command is optional, but highly recommended.
29It runs a basic correctness test which usually takes well under a minute.
30<FONT COLOR=green>
31<H3>Other platforms</h3>
32On non-Unix, non-Linux platforms, the collector is usually built by copying
33the appropriate makefile (see the platform-specific README in doc/README.xxx
34in the distribution) to the file "Makefile" (overwriting the copy of
35Makefile.direct that was originally there), and then typing "make"
36(or "nmake" or ...). This builds the library in the source tree. You may
37want to move it and the files in the include directory to a more convenient
38place.
39<P>
40If you use a makefile that does not require running a configure script,
41you should first look at the makefile, and adjust any options that are
42documented there.
43<P>
44If your platform provides a "make" utility, that is generally preferred
45to platform- and compiler- dependent "project" files. (At least that is the
46strong preference of the would-be maintainer of those project files.)
47<H3>Threads</h3>
48If you need thread support, configure the collector with
49<PRE>
50--enable-threads=posix --enable-thread-local-alloc --enable-parallel-mark
51</pre>
52instead of
53<TT>--disable-threads</tt>
54If your target is a real old-fashioned uniprocessor (no "hyperthreading",
55etc.) you will want to omit <TT>--enable-parallel-mark</tt>.
56<H3>C++</h3>
57You will need to include the C++ support, which unfortunately tends to
58be among the least portable parts of the collector, since it seems
59to rely on some corner cases of the language. On Linux, it
60suffices to add <TT>--enable-cplusplus</tt> to the configure options.
61</font>
62<H2>Writing the program</h2>
63You will need a
64<PRE>
65#include "gc.h"
66</pre>
67at the beginning of every file that allocates memory through the
68garbage collector. Call <TT>GC_MALLOC</tt> wherever you would
69have call <TT>malloc</tt>. This initializes memory to zero like
70<TT>calloc</tt>; there is no need to explicitly clear the
71result.
72<P>
73If you know that an object will not contain pointers to the
74garbage-collected heap, and you don't need it to be initialized,
75call <TT>GC_MALLOC_ATOMIC</tt> instead.
76<P>
77A function <TT>GC_FREE</tt> is provided but need not be called.
78For very small objects, your program will probably perform better if
79you do not call it, and let the collector do its job.
80<P>
81A <TT>GC_REALLOC</tt> function behaves like the C library <TT>realloc</tt>.
82It allocates uninitialized pointer-free memory if the original
83object was allocated that way.
84<P>
85The following program <TT>loop.c</tt> is a trivial example:
86<PRE>
87#include "gc.h"
88#include &lt;assert.h&gt;
89#include &lt;stdio.h&gt;
90
91int 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>
110It 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
112pointers to the garbage-collected heap in memory allocated with the system
113<TT>malloc</tt>.
114<H3>Other Platforms</h3>
115On some other platforms it is necessary to call <TT>GC_INIT()</tt> from the main program,
116which is presumed to be part of the main executable, not a dynamic library.
117This can never hurt, and is thus generally good practice.
118
119<H3>Threads</h3>
120For a multithreaded program some more rules apply:
121<UL>
122<LI>
123Files that either allocate through the GC <I>or make thread-related calls</i>
124should first define the macro <TT>GC_THREADS</tt>, and then
125include <TT>"gc.h"</tt>. On some platforms this will redefine some
126threads primitives, e.g. to let the collector keep track of thread creation.
127<LI>
128To take advantage of fast thread-local allocation, use the following instead
129of including <TT>gc.h</tt>:
130<PRE>
131#define GC_REDIRECT_TO_LOCAL
132#include "gc_local_alloc.h"
133</pre>
134This will cause GC_MALLOC and GC_MALLOC_ATOMIC to keep per-thread allocation
135caches, and greatly reduce the number of lock acquisitions during allocation.
136</ul>
137
138<H3>C++</h3>
139In the case of C++, you need to be especially careful not to store pointers
140to the garbage-collected heap in areas that are not traced by the collector.
141The collector includes some <A HREF="gcinterface.html">alternate interfaces</a>
142to make that easier.
143
144<H3>Debugging</h3>
145Additional debug checks can be performed by defining <TT>GC_DEBUG</tt> before
146including <TT>gc.h</tt>. Additional options are available if the collector
147is also built with <TT>--enable-full_debug</tt> and all allocations are
148performed with <TT>GC_DEBUG</tt> defined.
149
150<H3>What if I can't rewrite/recompile my program?</h3>
151You may be able to build the collector with <TT>--enable-redirect-malloc</tt>
152and set the <TT>LD_PRELOAD</tt> environment variable to point to the resulting
153library, thus replacing the standard <TT>malloc</tt> with its garbage-collected
154counterpart. 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
161The above application <TT>loop.c</tt> test program can be compiled and linked
162with
163
164<PRE>
165cc -I/home/xyz/gc/include loop.c /home/xyz/gc/lib/libgc.a -o loop
166</pre>
167
168The <TT>-I</tt> option directs the compiler to the right include
169directory. In this case, we list the static library
170directly on the compile line; the dynamic library could have been
171used instead, provided we arranged for the dynamic loader to find
172it, e.g. by setting <TT>LD_LIBRARY_PATH</tt>.
173
174<FONT COLOR=green>
175
176<H3>Threads</h3>
177
178On pthread platforms, you will of course also have to link with
179<TT>-lpthread</tt>,
180and compile with any thread-safety options required by your compiler.
181On some platforms, you may also need to link with <TT>-ldl</tt>
182or <TT>-lrt</tt>.
183Looking at threadlibs.c in the GC build directory
184should give you the appropriate
185list if a plain <TT>-lpthread</tt> doesn't work.
186
187</font>
188
189<H2>Running the executable</h2>
190
191The executable can of course be run normally, e.g. by typing
192
193<PRE>
194./loop
195</pre>
196
197The operation of the collector is affected by a number of environment variables.
198For example, setting <TT>GC_PRINT_STATS</tt> produces some
199GC statistics on stdout.
200See <TT>README.environment</tt> in the distribution for details.
201</body>
202</html>
Note: See TracBrowser for help on using the repository browser.