204 lines
9.5 KiB
HTML
204 lines
9.5 KiB
HTML
<!DOCTYPE HTML>
|
|
<HEAD>
|
|
<TITLE>Garbage Collector Interface</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
<H1>C Interface</h1>
|
|
On many platforms, a single-threaded garbage collector library can be built
|
|
to act as a plug-in malloc replacement. (Build with -DREDIRECT_MALLOC=GC_malloc
|
|
-DIGNORE_FREE.) This is often the best way to deal with third-party libraries
|
|
which leak or prematurely free objects. -DREDIRECT_MALLOC is intended
|
|
primarily as an easy way to adapt old code, not for new development.
|
|
<P>
|
|
New code should use the interface discussed below.
|
|
<P>
|
|
Code must be linked against the GC library. On most UNIX platforms,
|
|
this will be gc.a.
|
|
<P>
|
|
The following describes the standard C interface to the garbage collector.
|
|
It is not a complete definition of the interface. It describes only the
|
|
most commonly used functionality, approximately in decreasing order of
|
|
frequency of use. The description assumes an ANSI C compiler.
|
|
The full interface is described in
|
|
<A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a>
|
|
or <TT>gc.h</tt> in the distribution.
|
|
<P>
|
|
Clients should include gc.h.
|
|
<P>
|
|
In the case of multithreaded code,
|
|
gc.h should be included after the threads header file, and
|
|
after defining the appropriate GC_XXXX_THREADS macro.
|
|
(For 6.2alpha4 and later, simply defining GC_THREADS should suffice.)
|
|
Gc.h must be included
|
|
in files that use either GC or threads primitives, since threads primitives
|
|
will be redefined to cooperate with the GC on many platforms.
|
|
<DL>
|
|
<DT> <B>void * GC_MALLOC(size_t <I>nbytes</i>)</b>
|
|
<DD>
|
|
Allocates and clears <I>nbytes</i> of storage.
|
|
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 GC_MALLOC_UNCOLLECTABLE, however.)
|
|
GC_MALLOC is a macro which invokes GC_malloc by default or, if GC_DEBUG
|
|
is defined before gc.h is included, a debugging version that checks
|
|
occasionally for overwrite errors, and the like.
|
|
<DT> <B>void * GC_MALLOC_ATOMIC(size_t <I>nbytes</i>)</b>
|
|
<DD>
|
|
Allocates <I>nbytes</i> of storage.
|
|
Requires (amortized) time proportional to <I>nbytes</i>.
|
|
The resulting object will be automatically deallocated when unreferenced.
|
|
The client promises that the resulting object will never contain any pointers.
|
|
The memory is not cleared.
|
|
This is the preferred way to allocate strings, floating point arrays,
|
|
bitmaps, etc.
|
|
More precise information about pointer locations can be communicated to the
|
|
collector using the interface in
|
|
<A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gc_typedh.txt">gc_typed.h</a> in the distribution.
|
|
<DT> <B>void * GC_MALLOC_UNCOLLECTABLE(size_t <I>nbytes</i>)</b>
|
|
<DD>
|
|
Identical to GC_MALLOC, except that the resulting object is not automatically
|
|
deallocated. Unlike the system-provided malloc, the collector does
|
|
scan the object for pointers to garbage-collectable memory, even if the
|
|
block itself does not appear to be reachable. (Objects allocated in this way
|
|
are effectively treated as roots by the collector.)
|
|
<DT> <B> void * GC_REALLOC(void *old, size_t new_size) </b>
|
|
<DD>
|
|
Allocate a new object of the indicated size and copy (a prefix of) the
|
|
old object into the new object. The old object is reused in place if
|
|
convenient. If the original object was allocated with GC_malloc_atomic,
|
|
the new object is subject to the same constraints. If it was allocated
|
|
as an uncollectable object, then the new object is uncollectable, and
|
|
the old object (if different) is deallocated.
|
|
(Use GC_REALLOC with GC_MALLOC, etc.)
|
|
<DT> <B> void GC_FREE(void *dead) </b>
|
|
<DD>
|
|
Explicitly deallocate an object. Typically not useful for small
|
|
collectable objects. (Use GC_FREE with GC_MALLOC, etc.)
|
|
<DT> <B> void * GC_MALLOC_IGNORE_OFF_PAGE(size_t <I>nbytes</i>) </b>
|
|
<DD>
|
|
<DT> <B> void * GC_MALLOC_ATOMIC_IGNORE_OFF_PAGE(size_t <I>nbytes</i>) </b>
|
|
<DD>
|
|
Analogous to GC_MALLOC and GC_MALLOC_ATOMIC, except that the client
|
|
guarantees that as long
|
|
as the resulting object is of use, a pointer is maintained to someplace
|
|
inside the first 512 bytes of the object. This pointer should be declared
|
|
volatile to avoid interference from compiler optimizations.
|
|
(Other nonvolatile pointers to the object may exist as well.)
|
|
This is the
|
|
preferred way to allocate objects that are likely to be > 100KBytes in size.
|
|
It greatly reduces the risk that such objects will be accidentally retained
|
|
when they are no longer needed. Thus space usage may be significantly reduced.
|
|
<DT> <B> void GC_gcollect(void) </b>
|
|
<DD>
|
|
Explicitly force a garbage collection.
|
|
<DT> <B> void GC_enable_incremental(void) </b>
|
|
<DD>
|
|
Cause the garbage collector to perform a small amount of work
|
|
every few invocations of GC_malloc or the like, instead of performing
|
|
an entire collection at once. This is likely to increase total
|
|
running time. It will improve response on a platform that either has
|
|
suitable support in the garbage collector (Irix and most other Unix
|
|
versions, win32 if the collector was suitably built) or if "stubborn"
|
|
allocation is used (see <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a>).
|
|
On many platforms this interacts poorly with system calls
|
|
that write to the garbage collected heap.
|
|
<DT> <B> GC_warn_proc GC_set_warn_proc(GC_warn_proc p) </b>
|
|
<DD>
|
|
Replace the default procedure used by the collector to print warnings.
|
|
The collector
|
|
may otherwise write to sterr, most commonly because GC_malloc was used
|
|
in a situation in which GC_malloc_ignore_off_page would have been more
|
|
appropriate. See <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a> for details.
|
|
<DT> <B> void GC_register_finalizer(...) </b>
|
|
<DD>
|
|
Register a function to be called when an object becomes inaccessible.
|
|
This is often useful as a backup method for releasing system resources
|
|
(<I>e.g.</i> closing files) when the object referencing them becomes
|
|
inaccessible.
|
|
It is not an acceptable method to perform actions that must be performed
|
|
in a timely fashion.
|
|
See <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a> for details of the interface.
|
|
See <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/finalization.html">here</a> for a more detailed discussion
|
|
of the design.
|
|
<P>
|
|
Note that an object may become inaccessible before client code is done
|
|
operating on its fields. Suitable synchronization is usually required.
|
|
See <A HREF="http://portal.acm.org/citation.cfm?doid=604131.604153">here</a>
|
|
or <A HREF="http://www.hpl.hp.com/techreports/2002/HPL-2002-335.html">here</a>
|
|
for details.
|
|
</dl>
|
|
<P>
|
|
If you are concerned with multiprocessor performance and scalability,
|
|
you should consider enabling and using thread local allocation (<I>e.g.</i>
|
|
GC_LOCAL_MALLOC, see <TT>gc_local_alloc.h</tt>. If your platform
|
|
supports it, you should build the collector with parallel marking support
|
|
(-DPARALLEL_MARK, or --enable-parallel-mark).
|
|
<P>
|
|
If the collector is used in an environment in which pointer location
|
|
information for heap objects is easily available, this can be passed on
|
|
to the colllector using the interfaces in either <TT>gc_typed.h</tt>
|
|
or <TT>gc_gcj.h</tt>.
|
|
<P>
|
|
The collector distribution also includes a <B>string package</b> that takes
|
|
advantage of the collector. For details see
|
|
<A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/cordh.txt">cord.h</a>
|
|
|
|
<H1>C++ Interface</h1>
|
|
There are three distinct ways to use the collector from C++:
|
|
<DL>
|
|
<DT> <B> STL allocators </b>
|
|
<DD>
|
|
Users of the <A HREF="http://www.sgi.com/tech/stl">SGI extended STL</a>
|
|
can include <TT>new_gc_alloc.h</tt> before including
|
|
STL header files.
|
|
(<TT>gc_alloc.h</tt> corresponds to now obsolete versions of the
|
|
SGI STL.)
|
|
This defines SGI-style allocators
|
|
<UL>
|
|
<LI> alloc
|
|
<LI> single_client_alloc
|
|
<LI> gc_alloc
|
|
<LI> single_client_gc_alloc
|
|
</ul>
|
|
which may be used either directly to allocate memory or to instantiate
|
|
container templates. 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
|
|
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>.
|
|
<P>
|
|
Recent versions of the collector also include a more standard-conforming
|
|
allocator implemention in <TT>gc_allocator.h</tt>. It defines
|
|
<UL>
|
|
<LI> traceable_allocator
|
|
<LI> gc_allocator
|
|
</ul>
|
|
Again the former allocates uncollectable but traced memory.
|
|
This should work with any fully standard-conforming C++ compiler.
|
|
<DT> <B> Class inheritance based interface </b>
|
|
<DD>
|
|
Users may include gc_cpp.h and then cause members of certain classes to
|
|
be allocated in garbage collectable memory by inheriting from class gc.
|
|
For details see <A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gc_cpph.txt">gc_cpp.h</a>.
|
|
<DT> <B> C interface </b>
|
|
<DD>
|
|
It is also possible to use the C interface from
|
|
<A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a> directly.
|
|
On platforms which use malloc to implement ::new, it should usually be possible
|
|
to use a version of the collector that has been compiled as a malloc
|
|
replacement. It is also possible to replace ::new and other allocation
|
|
functions suitably.
|
|
<P>
|
|
Note that user-implemented small-block allocation often works poorly with
|
|
an underlying garbage-collected large block allocator, since the collector
|
|
has to view all objects accessible from the user's free list as reachable.
|
|
This is likely to cause problems if GC_malloc is used with something like
|
|
the original HP version of STL.
|
|
This approach works with the SGI versions of the STL only if the
|
|
<TT>malloc_alloc</tt> allocator is used.
|
|
</dl>
|
|
</body>
|
|
</html>
|