| <HTML> |
| <HEAD> |
| <TITLE>Using the Garbage Collector: A simple example</title> |
| </head> |
| <BODY> |
| <H1>Using the Garbage Collector: A simple example</h1> |
| The following consists of step-by-step instructions for building and |
| using the collector. We'll assume a Linux/gcc platform and |
| a single-threaded application. <FONT COLOR=green>The green |
| text contains information about other platforms or scenarios. |
| It can be skipped, especially on first reading</font>. |
| <H2>Building the collector</h2> |
| If you haven't already so, unpack the collector and enter |
| the newly created directory with |
| <PRE> |
| tar xvfz gc<version>.tar.gz |
| cd gc<version> |
| </pre> |
| <P> |
| You can configure, build, and install the collector in a private |
| directory, say /home/xyz/gc, with the following commands: |
| <PRE> |
| ./configure --prefix=/home/xyz/gc --disable-threads |
| make |
| make check |
| make install |
| </pre> |
| Here the "<TT>make check</tt>" command is optional, but highly recommended. |
| It runs a basic correctness test which usually takes well under a minute. |
| <FONT COLOR=green> |
| <H3>Other platforms</h3> |
| On non-Unix, non-Linux platforms, the collector is usually built by copying |
| the appropriate makefile (see the platform-specific README in doc/README.xxx |
| in the distribution) to the file "Makefile" (overwriting the copy of |
| Makefile.direct that was originally there), and then typing "make" |
| (or "nmake" or ...). This builds the library in the source tree. You may |
| want to move it and the files in the include directory to a more convenient |
| place. |
| <P> |
| If you use a makefile that does not require running a configure script, |
| you should first look at the makefile, and adjust any options that are |
| documented there. |
| <P> |
| If your platform provides a "make" utility, that is generally preferred |
| to platform- and compiler- dependent "project" files. (At least that is the |
| strong preference of the would-be maintainer of those project files.) |
| <H3>Threads</h3> |
| If you need thread support, configure the collector with |
| <PRE> |
| --enable-threads=posix --enable-thread-local-alloc --enable-parallel-mark |
| </pre> |
| instead of |
| <TT>--disable-threads</tt> |
| If your target is a real old-fashioned uniprocessor (no "hyperthreading", |
| etc.) you will want to omit <TT>--enable-parallel-mark</tt>. |
| <H3>C++</h3> |
| You will need to include the C++ support, which unfortunately tends to |
| be among the least portable parts of the collector, since it seems |
| to rely on some corner cases of the language. On Linux, it |
| suffices to add <TT>--enable-cplusplus</tt> to the configure options. |
| </font> |
| <H2>Writing the program</h2> |
| You will need a |
| <PRE> |
| #include "gc.h" |
| </pre> |
| at the beginning of every file that allocates memory through the |
| garbage collector. Call <TT>GC_MALLOC</tt> wherever you would |
| have call <TT>malloc</tt>. This initializes memory to zero like |
| <TT>calloc</tt>; there is no need to explicitly clear the |
| result. |
| <P> |
| If you know that an object will not contain pointers to the |
| garbage-collected heap, and you don't need it to be initialized, |
| call <TT>GC_MALLOC_ATOMIC</tt> instead. |
| <P> |
| A function <TT>GC_FREE</tt> is provided but need not be called. |
| For very small objects, your program will probably perform better if |
| you do not call it, and let the collector do its job. |
| <P> |
| A <TT>GC_REALLOC</tt> function behaves like the C library <TT>realloc</tt>. |
| It allocates uninitialized pointer-free memory if the original |
| object was allocated that way. |
| <P> |
| The following program <TT>loop.c</tt> is a trivial example: |
| <PRE> |
| #include "gc.h" |
| #include <assert.h> |
| #include <stdio.h> |
| |
| int main() |
| { |
| int i; |
| |
| GC_INIT(); /* Optional on Linux/X86; see below. */ |
| for (i = 0; i < 10000000; ++i) |
| { |
| int **p = (int **) GC_MALLOC(sizeof(int *)); |
| int *q = (int *) GC_MALLOC_ATOMIC(sizeof(int)); |
| assert(*p == 0); |
| *p = (int *) GC_REALLOC(q, 2 * sizeof(int)); |
| if (i % 100000 == 0) |
| printf("Heap size = %d\n", GC_get_heap_size()); |
| } |
| return 0; |
| } |
| </pre> |
| <FONT COLOR=green> |
| <H3>Interaction with the system malloc</h3> |
| It is usually best not to mix garbage-collected allocation with the system |
| <TT>malloc-free</tt>. If you do, you need to be careful not to store |
| pointers to the garbage-collected heap in memory allocated with the system |
| <TT>malloc</tt>. |
| <H3>Other Platforms</h3> |
| On some other platforms it is necessary to call <TT>GC_INIT()</tt> from the main program, |
| which is presumed to be part of the main executable, not a dynamic library. |
| This can never hurt, and is thus generally good practice. |
| |
| <H3>Threads</h3> |
| For a multithreaded program some more rules apply: |
| <UL> |
| <LI> |
| Files that either allocate through the GC <I>or make thread-related calls</i> |
| should first define the macro <TT>GC_THREADS</tt>, and then |
| include <TT>"gc.h"</tt>. On some platforms this will redefine some |
| threads primitives, e.g. to let the collector keep track of thread creation. |
| <LI> |
| To take advantage of fast thread-local allocation, use the following instead |
| of including <TT>gc.h</tt>: |
| <PRE> |
| #define GC_REDIRECT_TO_LOCAL |
| #include "gc_local_alloc.h" |
| </pre> |
| This will cause GC_MALLOC and GC_MALLOC_ATOMIC to keep per-thread allocation |
| caches, and greatly reduce the number of lock acquisitions during allocation. |
| </ul> |
| |
| <H3>C++</h3> |
| In the case of C++, you need to be especially careful not to store pointers |
| to the garbage-collected heap in areas that are not traced by the collector. |
| The collector includes some <A HREF="gcinterface.html">alternate interfaces</a> |
| to make that easier. |
| |
| <H3>Debugging</h3> |
| Additional debug checks can be performed by defining <TT>GC_DEBUG</tt> before |
| including <TT>gc.h</tt>. Additional options are available if the collector |
| is also built with <TT>--enable-full_debug</tt> and all allocations are |
| performed with <TT>GC_DEBUG</tt> defined. |
| |
| <H3>What if I can't rewrite/recompile my program?</h3> |
| You may be able to build the collector with <TT>--enable-redirect-malloc</tt> |
| and set the <TT>LD_PRELOAD</tt> environment variable to point to the resulting |
| library, thus replacing the standard <TT>malloc</tt> with its garbage-collected |
| counterpart. This is rather platform dependent. See the |
| <A HREF="leak.html">leak detection documentation</a> for some more details. |
| |
| </font> |
| |
| <H2>Compiling and linking</h2> |
| |
| The above application <TT>loop.c</tt> test program can be compiled and linked |
| with |
| |
| <PRE> |
| cc -I/home/xyz/gc/include loop.c /home/xyz/gc/lib/libgc.a -o loop |
| </pre> |
| |
| The <TT>-I</tt> option directs the compiler to the right include |
| directory. In this case, we list the static library |
| directly on the compile line; the dynamic library could have been |
| used instead, provided we arranged for the dynamic loader to find |
| it, e.g. by setting <TT>LD_LIBRARY_PATH</tt>. |
| |
| <FONT COLOR=green> |
| |
| <H3>Threads</h3> |
| |
| On pthread platforms, you will of course also have to link with |
| <TT>-lpthread</tt>, |
| and compile with any thread-safety options required by your compiler. |
| On some platforms, you may also need to link with <TT>-ldl</tt> |
| or <TT>-lrt</tt>. |
| Looking at threadlibs.c in the GC build directory |
| should give you the appropriate |
| list if a plain <TT>-lpthread</tt> doesn't work. |
| |
| </font> |
| |
| <H2>Running the executable</h2> |
| |
| The executable can of course be run normally, e.g. by typing |
| |
| <PRE> |
| ./loop |
| </pre> |
| |
| The operation of the collector is affected by a number of environment variables. |
| For example, setting <TT>GC_PRINT_STATS</tt> produces some |
| GC statistics on stdout. |
| See <TT>README.environment</tt> in the distribution for details. |
| </body> |
| </html> |