diff options
Diffstat (limited to 'boehm-gc/doc/gcinterface.html')
| -rw-r--r-- | boehm-gc/doc/gcinterface.html | 203 |
1 files changed, 203 insertions, 0 deletions
diff --git a/boehm-gc/doc/gcinterface.html b/boehm-gc/doc/gcinterface.html new file mode 100644 index 00000000000..7b336ec811b --- /dev/null +++ b/boehm-gc/doc/gcinterface.html @@ -0,0 +1,203 @@ +<!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> |