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 @@ - + + + Garbage Collector Interface @@ -8,7 +10,8 @@ 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 +which leak or prematurely free objects. +-DREDIRECT_MALLOC=GC_malloc is intended primarily as an easy way to adapt old code, not for new development.

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.

void GC_gcollect(void) @@ -152,8 +157,15 @@ for details.

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.

STL allocators

-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

    -
  • traceable_allocator -
  • gc_allocator +
  • traceable_allocator +
  • gc_allocator
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.

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

    -
  • alloc -
  • single_client_alloc -
  • gc_alloc -
  • single_client_gc_alloc +
  • alloc +
  • single_client_alloc +
  • gc_alloc +
  • single_client_gc_alloc
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.

For an example, click here. -

Class inheritance based interface +
Class inheritance based interface for new-based allocation
Users may include gc_cpp.h and then cause members of classes to be allocated in garbage collectable memory by having those classes