boehm-gc/doc/gcinterface.html - gcc - Git at Google

 <!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>
	<!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>