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