libgc/doc/simple_example.html

   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>
   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 &lt;assert.h&gt;
  89 #include &lt;stdio.h&gt;
  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>