boehm-gc/doc/simple_example.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html lang="en-us">
   3 <HEAD>
   4 <meta http-equiv="Content-Type" content="text/html;charset=US-ASCII" >
   5 <TITLE>Using the Garbage Collector: A simple example</title>
   6 </head>
   7 <BODY>
   8 <H1>Using the Garbage Collector: A simple example</h1>
   9 The following consists of step-by-step instructions for building and
  10 using the collector.  We'll assume a Linux/gcc platform and
  11 a single-threaded application.  <FONT COLOR=green>The green
  12 text contains information about other platforms or scenarios.
  13 It can be skipped, especially on first reading</font>.
  14 <H2>Building the collector</h2>
  15 If you haven't already so, unpack the collector and enter
  16 the newly created directory with
  17 <PRE>
  18 tar xvfz gc&lt;version&gt;.tar.gz
  19 cd gc&lt;version&gt;
  20 </pre>
  21 <P>
  22 You can configure, build, and install the collector in a private
  23 directory, say /home/xyz/gc, with the following commands:
  24 <PRE>
  25 ./configure --prefix=/home/xyz/gc --disable-threads
  26 make
  27 make check
  28 make install
  29 </pre>
  30 Here the "<TT>make check</tt>" command is optional, but highly recommended.
  31 It runs a basic correctness test which usually takes well under a minute.
  32 <H3><FONT COLOR=green>Other platforms</font></h3>
  33 <FONT COLOR=green>
  34 On non-Unix, non-Linux platforms, the collector is usually built by copying
  35 the appropriate makefile (see the platform-specific README in doc/README.xxx
  36 in the distribution) to the file "Makefile", and then typing "make"
  37 (or "nmake" or ...).  This builds the library in the source tree.  You may
  38 want to move it and the files in the include directory to a more convenient
  39 place.
  40 </font>
  41 <P>
  42 <FONT COLOR=green>
  43 If you use a makefile that does not require running a configure script,
  44 you should first look at the makefile, and adjust any options that are
  45 documented there.
  46 </font>
  47 <P>
  48 <FONT COLOR=green>
  49 If your platform provides a "make" utility, that is generally preferred
  50 to platform- and compiler- dependent "project" files.  (At least that is the
  51 strong preference of the would-be maintainer of those project files.)
  52 </font>
  53 <H3><FONT COLOR=green>Threads</font></h3>
  54 <FONT COLOR=green>
  55 If you need thread support, configure the collector with
  56 </font>
  57 <PRE style="color:green">
  58 --enable-threads=posix --enable-thread-local-alloc --enable-parallel-mark
  59 </pre>
  60 <FONT COLOR=green>
  61 instead of
  62 <TT>--disable-threads</tt>
  63 If your target is a real old-fashioned uniprocessor (no "hyperthreading",
  64 etc.) you will want to omit <TT>--enable-parallel-mark</tt>.
  65 </font>
  66 <H3><FONT COLOR=green>C++</font></h3>
  67 <FONT COLOR=green>
  68 You will need to include the C++ support, which unfortunately tends to
  69 be among the least portable parts of the collector, since it seems
  70 to rely on some corner cases of the language.  On Linux, it
  71 suffices to add <TT>--enable-cplusplus</tt> to the configure options.
  72 </font>
  73 <H2>Writing the program</h2>
  74 You will need a
  75 <PRE>
  76 #include "gc.h"
  77 </pre>
  78 at the beginning of every file that allocates memory through the
  79 garbage collector.  Call <TT>GC_MALLOC</tt> wherever you would
  80 have call <TT>malloc</tt>.  This initializes memory to zero like
  81 <TT>calloc</tt>; there is no need to explicitly clear the
  82 result.
  83 <P>
  84 If you know that an object will not contain pointers to the
  85 garbage-collected heap, and you don't need it to be initialized,
  86 call <TT>GC_MALLOC_ATOMIC</tt> instead.
  87 <P>
  88 A function <TT>GC_FREE</tt> is provided but need not be called.
  89 For very small objects, your program will probably perform better if
  90 you do not call it, and let the collector do its job.
  91 <P>
  92 A <TT>GC_REALLOC</tt> function behaves like the C library <TT>realloc</tt>.
  93 It allocates uninitialized pointer-free memory if the original
  94 object was allocated that way.
  95 <P>
  96 The following program <TT>loop.c</tt> is a trivial example:
  97 <PRE>
  98 #include "gc.h"
  99 #include &lt;assert.h&gt;
 100 #include &lt;stdio.h&gt;
 101
 102 int main()
 103 {
 104   int i;
 105
 106   GC_INIT();
 107   for (i = 0; i &lt; 10000000; ++i)
 108    {
 109      int **p = (int **) GC_MALLOC(sizeof(int *));
 110      int *q = (int *) GC_MALLOC_ATOMIC(sizeof(int));
 111      assert(*p == 0);
 112      *p = (int *) GC_REALLOC(q, 2 * sizeof(int));
 113      if (i % 100000 == 0)
 114        printf("Heap size = %d\n", GC_get_heap_size());
 115    }
 116   return 0;
 117 }
 118 </pre>
 119 <H3><FONT COLOR=green>Interaction with the system malloc</font></h3>
 120 <FONT COLOR=green>
 121 It is usually best not to mix garbage-collected allocation with the system
 122 <TT>malloc-free</tt>.  If you do, you need to be careful not to store
 123 pointers to the garbage-collected heap in memory allocated with the system
 124 <TT>malloc</tt>.
 125 </font>
 126
 127 <H3><FONT COLOR=green>Other Platforms</font></h3>
 128 <FONT COLOR=green>
 129 On some other platforms it is necessary to call <TT>GC_INIT()</tt> from the main program,
 130 which is presumed to be part of the main executable, not a dynamic library.
 131 This can never hurt, and is thus generally good practice.
 132 </font>
 133
 134 <H3><FONT COLOR=green>Threads</font></h3>
 135 <FONT COLOR=green>
 136 For a multithreaded program some more rules apply:
 137 </font>
 138 <UL>
 139 <LI>
 140 <FONT COLOR=green>
 141 Files that either allocate through the GC <I>or make thread-related calls</i>
 142 should first define the macro <TT>GC_THREADS</tt>, and then
 143 include <TT>"gc.h"</tt>.  On some platforms this will redefine some
 144 threads primitives, e.g. to let the collector keep track of thread creation.
 145 </font>
 146 <LI>
 147 <FONT COLOR=green>
 148 To take advantage of fast thread-local allocation in versions before 7.0,
 149 use the following instead
 150 of including <TT>gc.h</tt>:
 151 </font>
 152 <PRE style="color:green">
 153 #define GC_REDIRECT_TO_LOCAL
 154 #include "gc_local_alloc.h"
 155 </pre>
 156 <FONT COLOR=green>
 157 This will cause GC_MALLOC and GC_MALLOC_ATOMIC to keep per-thread allocation
 158 caches, and greatly reduce the number of lock acquisitions during allocation.
 159 For versions after 7.0, this happens implicitly if the collector is built
 160 with thread-local allocation enabled.
 161 </font>
 162 </ul>
 163
 164 <H3><FONT COLOR=green>C++</font></h3>
 165 <FONT COLOR=green>
 166 In the case of C++, you need to be especially careful not to store pointers
 167 to the garbage-collected heap in areas that are not traced by the collector.
 168 The collector includes some <A HREF="gcinterface.html">alternate interfaces</a>
 169 to make that easier.
 170 </font>
 171
 172 <H3><FONT COLOR=green>Debugging</font></h3>
 173 <FONT COLOR=green>
 174 Additional debug checks can be performed by defining <TT>GC_DEBUG</tt> before
 175 including <TT>gc.h</tt>.  Additional options are available if the collector
 176 is also built with <TT>--enable-gc-debug</tt> (<TT>--enable-full-debug</tt> in
 177 some older versions) and all allocations are
 178 performed with <TT>GC_DEBUG</tt> defined.
 179 </font>
 180
 181 <H3><FONT COLOR=green>What if I can't rewrite/recompile my program?</font></h3>
 182 <FONT COLOR=green>
 183 You may be able to build the collector with <TT>--enable-redirect-malloc</tt>
 184 and set the <TT>LD_PRELOAD</tt> environment variable to point to the resulting
 185 library, thus replacing the standard <TT>malloc</tt> with its garbage-collected
 186 counterpart.  This is rather platform dependent.  See the
 187 <A HREF="leak.html">leak detection documentation</a> for some more details.
 188 </font>
 189
 190 <H2>Compiling and linking</h2>
 191
 192 The above application <TT>loop.c</tt> test program can be compiled and linked
 193 with
 194
 195 <PRE>
 196 cc -I/home/xyz/gc/include loop.c /home/xyz/gc/lib/libgc.a -o loop
 197 </pre>
 198
 199 The <TT>-I</tt> option directs the compiler to the right include
 200 directory.  In this case, we list the static library
 201 directly on the compile line; the dynamic library could have been
 202 used instead, provided we arranged for the dynamic loader to find
 203 it, e.g. by setting <TT>LD_LIBRARY_PATH</tt>.
 204
 205 <H3><FONT COLOR=green>Threads</font></h3>
 206 <FONT COLOR=green>
 207 On pthread platforms, you will of course also have to link with
 208 <TT>-lpthread</tt>,
 209 and compile with any thread-safety options required by your compiler.
 210 On some platforms, you may also need to link with <TT>-ldl</tt>
 211 or <TT>-lrt</tt>.
 212 Looking at tools/threadlibs.c should give you the appropriate
 213 list if a plain <TT>-lpthread</tt> doesn't work.
 214 </font>
 215
 216 <H2>Running the executable</h2>
 217
 218 The executable can of course be run normally, e.g. by typing
 219
 220 <PRE>
 221 ./loop
 222 </pre>
 223
 224 The operation of the collector is affected by a number of environment variables.
 225 For example, setting <TT>GC_PRINT_STATS</tt> produces some
 226 GC statistics on stdout.
 227 See <TT>README.environment</tt> in the distribution for details.
 228 </body>
 229 </html>