aboutsummaryrefslogtreecommitdiff
path: root/boehm-gc/doc
diff options
context:
space:
mode:
authorBryce McKinlay <bryce@gcc.gnu.org>2004-08-12 22:14:30 +0100
committerBryce McKinlay <bryce@gcc.gnu.org>2004-08-12 22:14:30 +0100
commitaa7a966b44190612dc1a052849512af924e75ea3 (patch)
tree04a20c1272f19e0dc47db597960d24b86f18b6a6 /boehm-gc/doc
parent5c4dc10837d7f66311a5da622e054ea168483a5c (diff)
downloadgcc-aa7a966b44190612dc1a052849512af924e75ea3.zip
gcc-aa7a966b44190612dc1a052849512af924e75ea3.tar.gz
gcc-aa7a966b44190612dc1a052849512af924e75ea3.tar.bz2
This commit was generated by cvs2svn to compensate for changes in r85899,
which included commits to RCS files with non-trunk default branches. From-SVN: r85900
Diffstat (limited to 'boehm-gc/doc')
-rw-r--r--boehm-gc/doc/README.darwin34
-rw-r--r--boehm-gc/doc/gcinterface.html119
2 files changed, 110 insertions, 43 deletions
diff --git a/boehm-gc/doc/README.darwin b/boehm-gc/doc/README.darwin
index 3cd1b81..72d6040 100644
--- a/boehm-gc/doc/README.darwin
+++ b/boehm-gc/doc/README.darwin
@@ -1,5 +1,5 @@
-Darwin/MacOSX Support - July 22, 2003
-====================================
+Darwin/MacOSX Support - December 16, 2003
+=========================================
Important Usage Notes
=====================
@@ -15,7 +15,7 @@ run and perhaps called GC_malloc(), create an initialization routine
for each library to call GC_init():
#include <gc/gc.h>
-void my_library_init() { GC_init(); }
+extern "C" void my_library_init() { GC_init(); }
Compile this code into a my_library_init.o, and link it into your
dylib. When you link the dylib, pass the -init argument with
@@ -34,6 +34,12 @@ work reliably with workarounds for a few possible bugs in place however
these workaround may not work correctly in all cases. There may also
be additional problems that I have not found.
+Thread-local GC allocation will not work with threads that are not
+created using the GC-provided override of pthread_create(). Threads
+created without the GC-provided pthread_create() do not have the
+necessary data structures in the GC to store this data.
+
+
Implementation Information
==========================
Darwin/MacOSX support is nearly complete. Thread support is reliable on
@@ -42,11 +48,27 @@ Darwin versions (MacOSX 10.1). Shared library support had also been
added and the gc can be run from a shared library. There is currently only
support for Darwin/PPC although adding x86 support should be trivial.
-Thread support is implemented in terms of mach thread_suspend and
+Thread support is implemented in terms of mach thread_suspend and
thread_resume calls. These provide a very clean interface to thread
suspension. This implementation doesn't rely on pthread_kill so the
-code works on Darwin < 6.0 (MacOSX 10.1). All the code to stop the
-world is located in darwin_stop_world.c.
+code works on Darwin < 6.0 (MacOSX 10.1). All the code to stop and
+start the world is located in darwin_stop_world.c.
+
+Since not all uses of the GC enable clients to override pthread_create()
+before threads have been created, the code for stopping the world has
+been rewritten to look for threads using Mach kernel calls. Each
+thread identified in this way is suspended and resumed as above. In
+addition, since Mach kernel threads do not contain pointers to their
+stacks, a stack-walking function has been written to find the stack
+limits. Given an initial stack pointer (for the current thread, a
+pointer to a stack-allocated local variable will do; for a non-active
+thread, we grab the value of register 1 (on PowerPC)), it
+will walk the PPC Mach-O-ABI compliant stack chain until it reaches the
+top of the stack. This appears to work correctly for GCC-compiled C,
+C++, Objective-C, and Objective-C++ code, as well as for Java
+programs that use JNI. If you run code that does not follow the stack
+layout or stack pointer conventions laid out in the PPC Mach-O ABI,
+then this will likely crash the garbage collector.
The original incremental collector support unfortunatelly no longer works
on recent Darwin versions. It also relied on some undocumented kernel
diff --git a/boehm-gc/doc/gcinterface.html b/boehm-gc/doc/gcinterface.html
index 7b336ec..1716514 100644
--- a/boehm-gc/doc/gcinterface.html
+++ b/boehm-gc/doc/gcinterface.html
@@ -5,31 +5,33 @@
<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
+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
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.
+depending on how the collector is built, this will be <TT>gc.a</tt>
+or <TT>libgc.{a,so}</tt>.
<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.
+frequency of use.
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.
+Clients should include <TT>gc.h</tt>.
<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
+<TT>gc.h</tt> should be included after the threads header file, and
+after defining the appropriate <TT>GC_</tt><I>XXXX</i><TT>_THREADS</tt> macro.
+(For 6.2alpha4 and later, simply defining <TT>GC_THREADS</tt> should suffice.)
+The header file <TT>gc.h</tt> 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>
@@ -39,9 +41,10 @@ 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
+considered by the collector. (See <TT>GC_MALLOC_UNCOLLECTABLE</tt>, however.)
+<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
occasionally for overwrite errors, and the like.
<DT> <B>void * GC_MALLOC_ATOMIC(size_t <I>nbytes</i>)</b>
<DD>
@@ -57,60 +60,70 @@ 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
+Identical to <TT>GC_MALLOC</tt>,
+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>
+<DT> <B> void * GC_REALLOC(void *<I>old</i>, size_t <I>new_size</i>) </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,
+convenient. If the original object was allocated with
+<TT>GC_MALLOC_ATOMIC</tt>,
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>
+<DT> <B> void GC_FREE(void *<I>dead</i>) </b>
<DD>
Explicitly deallocate an object. Typically not useful for small
-collectable objects. (Use GC_FREE with GC_MALLOC, etc.)
+collectable objects.
<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
+Analogous to <TT>GC_MALLOC</tt> and <TT>GC_MALLOC_ATOMIC</tt>,
+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.
+preferred way to allocate objects that are likely to be &gt; 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_INIT(void) </b>
+<DD>
+On some platforms, it is necessary to invoke this
+<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.
<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
+every few invocations of <TT>GC_MALLOC</tt> 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
+suitable support in the garbage collector (Linux and most 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>).
+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>
+<DT> <B> GC_warn_proc GC_set_warn_proc(GC_warn_proc <I>p</i>) </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>
+<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
@@ -123,7 +136,8 @@ See <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/finalization.html">her
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.
+operating on objects referenced by 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.
@@ -131,13 +145,13 @@ for details.
<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
+<TT>GC_LOCAL_MALLOC</tt>, 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).
+(<TT>-DPARALLEL_MARK</tt>, or <TT>--enable-parallel-mark</tt>).
<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>
+to the collector 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
@@ -145,7 +159,31 @@ 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++:
+Usage of the collector from C++ is complicated by the fact that there
+are many "standard" ways to allocate memory in C++. The default ::new
+operator, default malloc, and default STL allocators allocate memory
+that is not garbage collected, and is not normally "traced" by the
+collector. This means that any pointers in memory allocated by these
+default allocators will not be seen by the collector. Garbage-collectable
+memory referenced only by pointers stored in such default-allocated
+objects is likely to be reclaimed prematurely by the collector.
+<P>
+It is the programmers responsibility to ensure that garbage-collectable
+memory is referenced by pointers stored in one of
+<UL>
+<LI> Program variables
+<LI> Garbage-collected objects
+<LI> Uncollected but "traceable" objects
+</ul>
+"Traceable" objects are not necessarily reclaimed by the collector,
+but are scanned for pointers to collectable objects.
+They are allocated by <TT>GC_MALLOC_UNCOLLECTABLE</tt>, as described
+above, and through some interfaces described below.
+<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:
<DL>
<DT> <B> STL allocators </b>
<DD>
@@ -170,7 +208,7 @@ multiple threads, but are faster.
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
+allocator implementation in <TT>gc_allocator.h</tt>. It defines
<UL>
<LI> traceable_allocator
<LI> gc_allocator
@@ -179,9 +217,15 @@ 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.
+Users may include gc_cpp.h and then cause members of classes to
+be allocated in garbage collectable memory by having those classes
+inherit 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>.
+<P>
+Linking against libgccpp in addition to the gc library overrides
+::new (and friends) to allocate traceable memory but uncollectable
+memory, making it safe to refer to collectable objects from the resulting
+memory.
<DT> <B> C interface </b>
<DD>
It is also possible to use the C interface from
@@ -189,14 +233,15 @@ It is also possible to use the C interface from
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.
+functions suitably, as is done by libgccpp.
<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
+This is likely to cause problems if <TT>GC_MALLOC</tt>
+is used with something like
the original HP version of STL.
-This approach works with the SGI versions of the STL only if the
+This approach works well with the SGI versions of the STL only if the
<TT>malloc_alloc</tt> allocator is used.
</dl>
</body>