diff options
| -rw-r--r-- | boehm-gc/NT_STATIC_THREADS_MAKEFILE | 60 | ||||
| -rw-r--r-- | boehm-gc/doc/simple_example.html | 202 | ||||
| -rw-r--r-- | boehm-gc/tests/middle.c | 25 |
3 files changed, 287 insertions, 0 deletions
diff --git a/boehm-gc/NT_STATIC_THREADS_MAKEFILE b/boehm-gc/NT_STATIC_THREADS_MAKEFILE new file mode 100644 index 00000000000..a7582af620b --- /dev/null +++ b/boehm-gc/NT_STATIC_THREADS_MAKEFILE @@ -0,0 +1,60 @@ +# Makefile for Windows NT. Assumes Microsoft compiler. +# DLLs are included in the root set under NT, but not under win32S. +# Use "nmake nodebug=1 all" for optimized versions of library, gctest and editor. + +MY_CPU=X86 +CPU=$(MY_CPU) +!include <ntwin32.mak> + +OBJS= alloc.obj reclaim.obj allchblk.obj misc.obj mach_dep.obj os_dep.obj mark_rts.obj headers.obj mark.obj obj_map.obj blacklst.obj finalize.obj new_hblk.obj dbg_mlc.obj malloc.obj stubborn.obj dyn_load.obj typd_mlc.obj ptr_chck.obj gc_cpp.obj mallocx.obj win32_threads.obj + +all: gctest.exe cord\de.exe test_cpp.exe + +.c.obj: + $(cc) $(cdebug) $(cflags) $(cvars) -Iinclude -DSILENT -DALL_INTERIOR_POINTERS -D__STDC__ -DGC_NOT_DLL -DGC_WIN32_THREADS $*.c /Fo$*.obj + +.cpp.obj: + $(cc) $(cdebug) $(cflags) $(cvars) -Iinclude -DSILENT -DALL_INTERIOR_POINTERS -DGC_NOT_DLL $*.CPP -DGC_WIN32_THREADS /Fo$*.obj + +$(OBJS) tests\test.obj: include\private\gc_priv.h include\private\gc_hdrs.h include\gc.h include\private\gcconfig.h include\private\gc_locks.h include\private\gc_pmark.h include\gc_mark.h + +gc.lib: $(OBJS) + lib /MACHINE:i386 /out:gc.lib $(OBJS) +# The original NT SDK used lib32 instead of lib + +gctest.exe: tests\test.obj gc.lib +# The following works for win32 debugging. For win32s debugging use debugtype:coff +# and add mapsympe line. +# This produces a "GUI" applications that opens no windows and writes to the log file +# "gc.log". This is done to make the result runnable under win32s. + $(link) -debug:full -debugtype:cv $(guiflags) -stack:131072 -out:$*.exe tests\test.obj $(guilibs) gc.lib +# mapsympe -n -o gctest.sym gctest.exe + +cord\de_win.rbj: cord\de_win.res + cvtres /MACHINE:$(MY_CPU) /OUT:cord\de_win.rbj cord\de_win.res + +cord\de.obj cord\de_win.obj: include\cord.h include\private\cord_pos.h cord\de_win.h cord\de_cmds.h + +cord\de_win.res: cord\de_win.rc cord\de_win.h cord\de_cmds.h + $(rc) $(rcvars) -r -fo cord\de_win.res $(cvars) cord\de_win.rc + +# Cord/de is a real win32 gui application. +cord\de.exe: cord\cordbscs.obj cord\cordxtra.obj cord\de.obj cord\de_win.obj cord\de_win.rbj gc.lib + $(link) -debug:full -debugtype:cv $(guiflags) -stack:16384 -out:cord\de.exe cord\cordbscs.obj cord\cordxtra.obj cord\de.obj cord\de_win.obj cord\de_win.rbj gc.lib $(guilibs) + +gc_cpp.obj: include\gc_cpp.h include\gc.h + +gc_cpp.cpp: gc_cpp.cc + copy gc_cpp.cc gc_cpp.cpp + +test_cpp.cpp: tests\test_cpp.cc + copy tests\test_cpp.cc test_cpp.cpp + +# This generates the C++ test executable. The executable expects +# a single numeric argument, which is the number of iterations. +# The output appears in the file "gc.log". +test_cpp.exe: test_cpp.obj include\gc_cpp.h include\gc.h gc.lib + $(link) -debug:full -debugtype:cv $(guiflags) -stack:16384 -out:test_cpp.exe test_cpp.obj gc.lib $(guilibs) + + + diff --git a/boehm-gc/doc/simple_example.html b/boehm-gc/doc/simple_example.html new file mode 100644 index 00000000000..0bc0953ef03 --- /dev/null +++ b/boehm-gc/doc/simple_example.html @@ -0,0 +1,202 @@ +<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> diff --git a/boehm-gc/tests/middle.c b/boehm-gc/tests/middle.c new file mode 100644 index 00000000000..5d9360af521 --- /dev/null +++ b/boehm-gc/tests/middle.c @@ -0,0 +1,25 @@ +/* + * Test at the boundary between small and large objects. + * Inspired by a test case from Zoltan Varga. + */ +#include <gc.h> +#include <stdio.h> + +int main () +{ + int i; + + GC_all_interior_pointers = 0; + + for (i = 0; i < 20000; ++i) { + GC_malloc_atomic (4096); + GC_malloc (4096); + } + for (i = 0; i < 20000; ++i) { + GC_malloc_atomic (2048); + GC_malloc (2048); + } + printf("Final heap size is %ld\n", GC_get_heap_size()); + return 0; +} + |
