X-Git-Url: http://wien.tomnetworks.com/gitweb/?a=blobdiff_plain;f=src%2Fmm%2Fboehm-gc%2Fdoc%2Fgcinterface.html;h=bb0995d86f1dd29d024dae36fb3befd3ca8ef1d6;hb=c83bff94e40ee0a218a39931af17814d1a42cb5c;hp=74230aa6caee465d4e677511eaa4b6a557585834;hpb=ac08f7c84b2d43f9c017e6df71bdd804adcfdcd6;p=cacao.git diff --git a/src/mm/boehm-gc/doc/gcinterface.html b/src/mm/boehm-gc/doc/gcinterface.html index 74230aa6c..bb0995d86 100644 --- a/src/mm/boehm-gc/doc/gcinterface.html +++ b/src/mm/boehm-gc/doc/gcinterface.html @@ -1,5 +1,7 @@ - + +
+
New code should use the interface discussed below.
@@ -47,7 +50,9 @@ Allocates and clears nbytes of storage.
Requires (amortized) time proportional to nbytes.
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.)
+considered by the collector. (See GC_MALLOC_UNCOLLECTABLE, however.
+Building the collector with -DREDIRECT_MALLOC=GC_malloc_uncollectable
+is often a way around this.)
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
@@ -106,7 +111,7 @@ On some platforms, it is necessary to invoke this
from the main executable, not from a dynamic library, 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 malloc
is not redirected to GC_malloc.
If you are concerned with multiprocessor performance and scalability,
-you should consider enabling and using thread local allocation (e.g.
-GC_LOCAL_MALLOC, see gc_local_alloc.h. If your platform
+you should consider enabling and using thread local allocation.
+For GC versions before 7.0, use e.g.
+GC_LOCAL_MALLOC and see gc_local_alloc.h;
+for later versions enabling thread-local allocations when the collector
+library is built changes the
+implementation of GC_MALLOC, so the client doesn't need to
+change.
+
+If your platform
supports it, you should build the collector with parallel marking support
(-DPARALLEL_MARK, or --enable-parallel-mark).
@@ -206,16 +218,18 @@ proper repair requires platform hooks.)
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
+gc_allocator.
-Recent versions of the collector also include a more standard-conforming
+Recent versions of the collector include a hopefully standard-conforming
allocator implementation in gc_allocator.h. It defines
Users of the SGI extended STL
or its derivatives (including most g++ versions)
-can alternatively include new_gc_alloc.h before including
-STL header files.
+may instead be able to include new_gc_alloc.h before including
+STL header files. This is increasingly discouraged.
(gc_alloc.h corresponds to now obsolete versions of the
SGI STL.) This interface is no longer recommended, but it has existed
for much longer.
This defines SGI-style allocators
For an example, click here.
-
-
which may be used either directly to allocate memory or to instantiate
container templates.
@@ -226,26 +240,26 @@ These should work with any fully standard-conforming C++ compiler.
-
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 single_client versions are not safe for concurrent access by
multiple threads, but are faster.