-<!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>
to act as a plug-in malloc replacement.
(Build with <TT>-DREDIRECT_MALLOC=GC_malloc -DIGNORE_FREE</tt>.)
This is often the best way to deal with third-party libraries
-which leak or prematurely free objects. <TT>-DREDIRECT_MALLOC</tt> is intended
+which leak or prematurely free objects.
+<TT>-DREDIRECT_MALLOC=GC_malloc</tt> is intended
primarily as an easy way to adapt old code, not for new development.
<P>
New code should use the interface discussed below.
Requires (amortized) time proportional to <I>nbytes</i>.
The resulting object will be automatically deallocated when unreferenced.
References from objects allocated with the system malloc are usually not
-considered by the collector. (See <TT>GC_MALLOC_UNCOLLECTABLE</tt>, however.)
+considered by the collector. (See <TT>GC_MALLOC_UNCOLLECTABLE</tt>, however.
+Building the collector with <TT>-DREDIRECT_MALLOC=GC_malloc_uncollectable
+is often a way around this.)
<TT>GC_MALLOC</tt> is a macro which invokes <TT>GC_malloc</tt> by default or,
if <TT>GC_DEBUG</tt>
is defined before <TT>gc.h</tt> is included, a debugging version that checks
<I>from the main executable, not from a dynamic library,</i> before
the initial invocation of a GC routine. It is recommended that this be done
in portable code, though we try to ensure that it expands to a no-op
-on as many platforms as possible. As of GC 7.0, it is required if
+on as many platforms as possible. In GC 7.0, it was required if
thread-local allocation is enabled in the collector build, and <TT>malloc</tt>
is not redirected to <TT>GC_malloc</tt>.
<DT> <B> void GC_gcollect(void) </b>
</dl>
<P>
If you are concerned with multiprocessor performance and scalability,
-you should consider enabling and using thread local allocation (<I>e.g.</i>
-<TT>GC_LOCAL_MALLOC</tt>, see <TT>gc_local_alloc.h</tt>. If your platform
+you should consider enabling and using thread local allocation.
+For GC versions before 7.0, use <I>e.g.</i>
+<TT>GC_LOCAL_MALLOC</tt> and see <TT>gc_local_alloc.h</tt>;
+for later versions enabling thread-local allocations when the collector
+library is built changes the
+implementation of <TT>GC_MALLOC</tt>, so the client doesn't need to
+change.
+<P>
+If your platform
supports it, you should build the collector with parallel marking support
(<TT>-DPARALLEL_MARK</tt>, or <TT>--enable-parallel-mark</tt>).
<P>
The easiest way to ensure that collectable objects are properly referenced
is to allocate only collectable objects. This requires that every
allocation go through one of the following interfaces, each one of
-which replaces a standard C++ allocation mechanism:
+which replaces a standard C++ allocation mechanism. Note that
+this requires that all STL containers be explicitly instantiated with
+<TT>gc_allocator</tt>.
<DL>
<DT> <B> STL allocators </b>
<DD>
<P>
-Recent versions of the collector also include a more standard-conforming
+Recent versions of the collector include a hopefully standard-conforming
allocator implementation in <TT>gc_allocator.h</tt>. It defines
<UL>
-<LI> traceable_allocator
-<LI> gc_allocator
+<LI> <TT>traceable_allocator</tt>
+<LI> <TT>gc_allocator</tt>
</ul>
which may be used either directly to allocate memory or to instantiate
container templates.
<P>
Users of the <A HREF="http://www.sgi.com/tech/stl">SGI extended STL</a>
or its derivatives (including most g++ versions)
-can alternatively include <TT>new_gc_alloc.h</tt> before including
-STL header files.
+may instead be able to include <TT>new_gc_alloc.h</tt> before including
+STL header files. This is increasingly discouraged.
(<TT>gc_alloc.h</tt> corresponds to now obsolete versions of the
SGI STL.) This interface is no longer recommended, but it has existed
for much longer.
<P>
This defines SGI-style allocators
<UL>
-<LI> alloc
-<LI> single_client_alloc
-<LI> gc_alloc
-<LI> single_client_gc_alloc
+<LI> <TT>alloc</tt>
+<LI> <TT>single_client_alloc</tt>
+<LI> <TT>gc_alloc</tt>
+<LI> <TT>single_client_gc_alloc</tt>
</ul>
The first two allocate uncollectable but traced
memory, while the second two allocate collectable memory.
-The single_client versions are not safe for concurrent access by
+The <TT>single_client</tt> versions are not safe for concurrent access by
multiple threads, but are faster.
<P>
For an example, click <A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_alloc_exC.txt">here</a>.
-<DT> <B> Class inheritance based interface </b>
+<DT> <B> Class inheritance based interface for new-based allocation</b>
<DD>
Users may include gc_cpp.h and then cause members of classes to
be allocated in garbage collectable memory by having those classes
projects / cacao.git / blobdiff