+2008-08-27 Hans Boehm <Hans.Boehm@hp.com>
+ * doc/simple_example.html: update --enable-full-debug reference,
+ Make HTML formatting standards compliant.
+ * doc/debugging.html, doc/leak.html: Fix HTML formatting bugs.
+ * doc/gcinterface.html: specify encoding.
+
2008-08-27 Hans Boehm <Hans.Boehm@hp.com> (with help from Marco Maggi)
* doc/simple_example.html: Update thread-local allocation
description.
-<HTML>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html lang="en-us">
<HEAD>
+<meta http-equiv="Content-Type" content="text/html;charset=US-ASCII" >
<TITLE>Debugging Garbage Collector Related Problems</title>
</head>
<BODY>
size_t old_size = GC_size(p);
void * result;
- if (new_size <= 10000) return(GC_realloc(p, new_size));
- if (new_size <= old_size) return(p);
+ if (new_size <= 10000) return(GC_realloc(p, new_size));
+ if (new_size <= old_size) return(p);
result = GC_malloc_ignore_off_page(new_size);
if (result == 0) return(0);
memcpy(result,p,old_size);
to allocate large objects. (See <TT>gc.h</tt> and above for details.
Large means > 100K in most environments.)
<LI> If your heap size is larger than 100MB or so, build the collector with
--DLARGE_CONFIG. This allows the collector to keep more precise black-list
+<TT>-DLARGE_CONFIG</tt>.
+This allows the collector to keep more precise black-list
information.
<LI> If you are using heaps close to, or larger than, a gigabyte on a 32-bit
machine, you may want to consider moving to a platform with 64-bit pointers.
-<!DOCTYPE HTML>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html lang="en-us">
<HEAD>
+<meta http-equiv="Content-Type" content="text/html;charset=US-ASCII" >
<TITLE>Garbage Collector Interface</TITLE>
</HEAD>
<BODY>
-<HTML>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html lang="en-us">
<HEAD>
+<meta http-equiv="Content-Type" content="text/html;charset=US-ASCII" >
<TITLE>Using the Garbage Collector as Leak Detector</title>
</head>
<BODY>
features:
<OL>
<LI> Leak detection mode can be initiated at run-time by
-setting GC_find_leak instead of building the collector with FIND_LEAK
+setting <TT>GC_find_leak</tt> instead of building the
+collector with <TT>FIND_LEAK</tt>
defined. This variable should be set to a nonzero value
at program startup.
<LI> Leaked objects should be reported and then correctly garbage collected.
<P>
To use the collector as a leak detector, follow the following steps:
<OL>
-<LI> Build the collector with -DFIND_LEAK. Otherwise use default
+<LI> Build the collector with <TT>-DFIND_LEAK</tt>. Otherwise use default
build options.
<LI> Change the program so that all allocation and deallocation goes
through the garbage collector.
#define CHECK_LEAKS() GC_gcollect()
</pre>
<P>
-Assume the collector has been built with -DFIND_LEAK. (For very
-new versions of the collector, we could instead add the statement
-<TT>GC_find_leak = 1</tt> as the first statement in <TT>main</tt>.
+Assume the collector has been built with <TT>-DFIND_LEAK</tt>. (For
+newer versions of the collector, we could instead add the statement
+<TT>GC_find_leak = 1</tt> as the first statement in <TT>main()</tt>.
<P>
The program to be tested for leaks can then look like:
<PRE>
int i;
/* GC_find_leak = 1; for new collector versions not */
/* compiled with -DFIND_LEAK. */
- for (i = 0; i < 10; ++i) {
+ for (i = 0; i < 10; ++i) {
p[i] = malloc(sizeof(int)+i);
}
- for (i = 1; i < 10; ++i) {
+ for (i = 1; i < 10; ++i) {
free(p[i]);
}
- for (i = 0; i < 9; ++i) {
+ for (i = 0; i < 9; ++i) {
p[i] = malloc(sizeof(int)+i);
}
CHECK_LEAKS();
a very recent (7.0alpha7+) collector version on Linux.</i>
On most platforms this does not
work at all for multithreaded programs.
-<LI> If possible, ensure that the addr2line program is installed in
-/usr/bin. (It comes with RedHat Linux.)
-<LI> If possible, compile a.out with full debug information.
+<LI> If possible, ensure that the <TT>addr2line</tt> program is installed in
+<TT>/usr/bin</tt>. (It comes with most Linux distributions.)
+<LI> If possible, compile your program, which we'll call <TT>a.out</tt>,
+with full debug information.
This will improve the quality of the leak reports. With this approach, it is
-no longer necessary to call GC_ routines explicitly, though that can also
+no longer necessary to call <TT>GC_</tt> routines explicitly,
+though that can also
improve the quality of the leak reports.
<LI> Build the collector and install it in directory <I>foo</i> as follows:
<UL>
<LI> <TT>make</tt>
<LI> <TT>make install</tt>
</ul>
-With a very recent collector on Linux, it may be safe to omit the <TT>--disable-threads</tt>.
+With a very recent collector on Linux, it may sometimes be safe to omit
+the <TT>--disable-threads</tt>. But the combination of thread support
+and <TT>malloc</tt> replacement is not yet rock solid.
<LI> Set environment variables as follows:
<UL>
-<LI> LD_PRELOAD=<I>foo</i>/lib/libgc.so
-<LI> GC_FIND_LEAK
-<LI> You may also want to set GC_PRINT_STATS (to confirm that the collector
-is running) and/or GC_LOOP_ON_ABORT (to facilitate debugging from another
+<LI> <TT>LD_PRELOAD=</tt><I>foo</i><TT>/lib/libgc.so</tt>
+<LI> <TT>GC_FIND_LEAK</tt>
+<LI> You may also want to set <TT>GC_PRINT_STATS</tt>
+(to confirm that the collector is running) and/or
+<TT>GC_LOOP_ON_ABORT</tt> (to facilitate debugging from another
window if something goes wrong).
-</ul
-<LI> Simply run a.out as you normally would. Note that if you run anything
+</ul>
+<LI> Simply run <TT>a.out</tt> as you normally would. Note that if you run anything
else (<I>e.g.</i> your editor) with those environment variables set,
it will also be leak tested. This may or may not be useful and/or
embarrassing. It can generate
-<HTML>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
+<html lang="en-us">
<HEAD>
+<meta http-equiv="Content-Type" content="text/html;charset=US-ASCII" >
<TITLE>Using the Garbage Collector: A simple example</title>
</head>
<BODY>
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>
+tar xvfz gc<version>.tar.gz
+cd gc<version>
</pre>
<P>
You can configure, build, and install the collector in a private
</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.
+<H3><FONT COLOR=green>Other platforms</font></h3>
<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
(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.
+</font>
<P>
+<FONT COLOR=green>
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.
+</font>
<P>
+<FONT COLOR=green>
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>
+</font>
+<H3><FONT COLOR=green>Threads</font></h3>
+<FONT COLOR=green>
If you need thread support, configure the collector with
-<PRE>
+</font>
+<PRE style="color:green">
--enable-threads=posix --enable-thread-local-alloc --enable-parallel-mark
</pre>
+<FONT COLOR=green>
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>
+</font>
+<H3><FONT COLOR=green>C++</font></h3>
+<FONT COLOR=green>
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
int i;
GC_INIT(); /* Optional on Linux/X86; see below. */
- for (i = 0; i < 10000000; ++i)
+ for (i = 0; i < 10000000; ++i)
{
int **p = (int **) GC_MALLOC(sizeof(int *));
int *q = (int *) GC_MALLOC_ATOMIC(sizeof(int));
return 0;
}
</pre>
+<H3><FONT COLOR=green>Interaction with the system malloc</font></h3>
<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>
+</font>
+
+<H3><FONT COLOR=green>Other Platforms</font></h3>
+<FONT COLOR=green>
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.
+</font>
-<H3>Threads</h3>
+<H3><FONT COLOR=green>Threads</font></h3>
+<FONT COLOR=green>
For a multithreaded program some more rules apply:
+</font>
<UL>
<LI>
+<FONT COLOR=green>
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.
+</font>
<LI>
+<FONT COLOR=green>
To take advantage of fast thread-local allocation in versions before 7.0,
use the following instead
of including <TT>gc.h</tt>:
-<PRE>
+</font>
+<PRE style="color:green">
#define GC_REDIRECT_TO_LOCAL
#include "gc_local_alloc.h"
</pre>
+<FONT COLOR=green>
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.
For versions after 7.0, this happens implicitly if the collector is built
with thread-local allocation enabled.
+</font>
</ul>
-<H3>C++</h3>
+<H3><FONT COLOR=green>C++</font></h3>
+<FONT COLOR=green>
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.
+</font>
-<H3>Debugging</h3>
+<H3><FONT COLOR=green>Debugging</font></h3>
+<FONT COLOR=green>
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
+is also built with <TT>--enable-gc-debug</tt> (<TT>--enable-full-debug</tt> in
+some older versions) and all allocations are
performed with <TT>GC_DEBUG</tt> defined.
+</font>
-<H3>What if I can't rewrite/recompile my program?</h3>
+<H3><FONT COLOR=green>What if I can't rewrite/recompile my program?</font></h3>
+<FONT COLOR=green>
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>
used instead, provided we arranged for the dynamic loader to find
it, e.g. by setting <TT>LD_LIBRARY_PATH</tt>.
+<H3><FONT COLOR=green>Threads</font></h3>
<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.
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>
projects / platform / upstream / libgc.git / commitdiff