diff options
Diffstat (limited to 'boehm-gc/doc/simple_example.html')
| -rw-r--r-- | boehm-gc/doc/simple_example.html | 202 |
1 files changed, 0 insertions, 202 deletions
diff --git a/boehm-gc/doc/simple_example.html b/boehm-gc/doc/simple_example.html deleted file mode 100644 index 0bc0953ef03..00000000000 --- a/boehm-gc/doc/simple_example.html +++ /dev/null @@ -1,202 +0,0 @@ -<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> |