Annotation of OpenXM_contrib2/asir2000/gc/doc/gcinterface.html, Revision 1.1
1.1 ! noro 1: <!DOCTYPE HTML>
! 2: <HEAD>
! 3: <TITLE>Garbage Collector Interface</TITLE>
! 4: </HEAD>
! 5: <BODY>
! 6: <H1>C Interface</h1>
! 7: On many platforms, a single-threaded garbage collector library can be built
! 8: to act as a plug-in malloc replacement. (Build with -DREDIRECT_MALLOC=GC_malloc
! 9: -DIGNORE_FREE.) This is often the best way to deal with third-party libraries
! 10: which leak or prematurely free objects. -DREDIRECT_MALLOC is intended
! 11: primarily as an easy way to adapt old code, not for new development.
! 12: <P>
! 13: New code should use the interface discussed below.
! 14: <P>
! 15: Code must be linked against the GC library. On most UNIX platforms,
! 16: this will be gc.a.
! 17: <P>
! 18: The following describes the standard C interface to the garbage collector.
! 19: It is not a complete definition of the interface. It describes only the
! 20: most commonly used functionality, approximately in decreasing order of
! 21: frequency of use. The description assumes an ANSI C compiler.
! 22: The full interface is described in
! 23: <A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a>
! 24: or <TT>gc.h</tt> in the distribution.
! 25: <P>
! 26: Clients should include gc.h.
! 27: <P>
! 28: In the case of multithreaded code,
! 29: gc.h should be included after the threads header file, and
! 30: after defining the appropriate GC_XXXX_THREADS macro.
! 31: (For 6.2alpha4 and later, simply defining GC_THREADS should suffice.)
! 32: Gc.h must be included
! 33: in files that use either GC or threads primitives, since threads primitives
! 34: will be redefined to cooperate with the GC on many platforms.
! 35: <DL>
! 36: <DT> <B>void * GC_MALLOC(size_t <I>nbytes</i>)</b>
! 37: <DD>
! 38: Allocates and clears <I>nbytes</i> of storage.
! 39: Requires (amortized) time proportional to <I>nbytes</i>.
! 40: The resulting object will be automatically deallocated when unreferenced.
! 41: References from objects allocated with the system malloc are usually not
! 42: considered by the collector. (See GC_MALLOC_UNCOLLECTABLE, however.)
! 43: GC_MALLOC is a macro which invokes GC_malloc by default or, if GC_DEBUG
! 44: is defined before gc.h is included, a debugging version that checks
! 45: occasionally for overwrite errors, and the like.
! 46: <DT> <B>void * GC_MALLOC_ATOMIC(size_t <I>nbytes</i>)</b>
! 47: <DD>
! 48: Allocates <I>nbytes</i> of storage.
! 49: Requires (amortized) time proportional to <I>nbytes</i>.
! 50: The resulting object will be automatically deallocated when unreferenced.
! 51: The client promises that the resulting object will never contain any pointers.
! 52: The memory is not cleared.
! 53: This is the preferred way to allocate strings, floating point arrays,
! 54: bitmaps, etc.
! 55: More precise information about pointer locations can be communicated to the
! 56: collector using the interface in
! 57: <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gc_typedh.txt">gc_typed.h</a> in the distribution.
! 58: <DT> <B>void * GC_MALLOC_UNCOLLECTABLE(size_t <I>nbytes</i>)</b>
! 59: <DD>
! 60: Identical to GC_MALLOC, except that the resulting object is not automatically
! 61: deallocated. Unlike the system-provided malloc, the collector does
! 62: scan the object for pointers to garbage-collectable memory, even if the
! 63: block itself does not appear to be reachable. (Objects allocated in this way
! 64: are effectively treated as roots by the collector.)
! 65: <DT> <B> void * GC_REALLOC(void *old, size_t new_size) </b>
! 66: <DD>
! 67: Allocate a new object of the indicated size and copy (a prefix of) the
! 68: old object into the new object. The old object is reused in place if
! 69: convenient. If the original object was allocated with GC_malloc_atomic,
! 70: the new object is subject to the same constraints. If it was allocated
! 71: as an uncollectable object, then the new object is uncollectable, and
! 72: the old object (if different) is deallocated.
! 73: (Use GC_REALLOC with GC_MALLOC, etc.)
! 74: <DT> <B> void GC_FREE(void *dead) </b>
! 75: <DD>
! 76: Explicitly deallocate an object. Typically not useful for small
! 77: collectable objects. (Use GC_FREE with GC_MALLOC, etc.)
! 78: <DT> <B> void * GC_MALLOC_IGNORE_OFF_PAGE(size_t <I>nbytes</i>) </b>
! 79: <DD>
! 80: <DT> <B> void * GC_MALLOC_ATOMIC_IGNORE_OFF_PAGE(size_t <I>nbytes</i>) </b>
! 81: <DD>
! 82: Analogous to GC_MALLOC and GC_MALLOC_ATOMIC, except that the client
! 83: guarantees that as long
! 84: as the resulting object is of use, a pointer is maintained to someplace
! 85: inside the first 512 bytes of the object. This pointer should be declared
! 86: volatile to avoid interference from compiler optimizations.
! 87: (Other nonvolatile pointers to the object may exist as well.)
! 88: This is the
! 89: preferred way to allocate objects that are likely to be > 100KBytes in size.
! 90: It greatly reduces the risk that such objects will be accidentally retained
! 91: when they are no longer needed. Thus space usage may be significantly reduced.
! 92: <DT> <B> void GC_gcollect(void) </b>
! 93: <DD>
! 94: Explicitly force a garbage collection.
! 95: <DT> <B> void GC_enable_incremental(void) </b>
! 96: <DD>
! 97: Cause the garbage collector to perform a small amount of work
! 98: every few invocations of GC_malloc or the like, instead of performing
! 99: an entire collection at once. This is likely to increase total
! 100: running time. It will improve response on a platform that either has
! 101: suitable support in the garbage collector (Irix and most other Unix
! 102: versions, win32 if the collector was suitably built) or if "stubborn"
! 103: allocation is used (see <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a>).
! 104: On many platforms this interacts poorly with system calls
! 105: that write to the garbage collected heap.
! 106: <DT> <B> GC_warn_proc GC_set_warn_proc(GC_warn_proc p) </b>
! 107: <DD>
! 108: Replace the default procedure used by the collector to print warnings.
! 109: The collector
! 110: may otherwise write to sterr, most commonly because GC_malloc was used
! 111: in a situation in which GC_malloc_ignore_off_page would have been more
! 112: appropriate. See <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a> for details.
! 113: <DT> <B> void GC_register_finalizer(...) </b>
! 114: <DD>
! 115: Register a function to be called when an object becomes inaccessible.
! 116: This is often useful as a backup method for releasing system resources
! 117: (<I>e.g.</i> closing files) when the object referencing them becomes
! 118: inaccessible.
! 119: It is not an acceptable method to perform actions that must be performed
! 120: in a timely fashion.
! 121: See <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a> for details of the interface.
! 122: See <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/finalization.html">here</a> for a more detailed discussion
! 123: of the design.
! 124: <P>
! 125: Note that an object may become inaccessible before client code is done
! 126: operating on its fields. Suitable synchronization is usually required.
! 127: See <A HREF="http://portal.acm.org/citation.cfm?doid=604131.604153">here</a>
! 128: or <A HREF="http://www.hpl.hp.com/techreports/2002/HPL-2002-335.html">here</a>
! 129: for details.
! 130: </dl>
! 131: <P>
! 132: If you are concerned with multiprocessor performance and scalability,
! 133: you should consider enabling and using thread local allocation (<I>e.g.</i>
! 134: GC_LOCAL_MALLOC, see <TT>gc_local_alloc.h</tt>. If your platform
! 135: supports it, you should build the collector with parallel marking support
! 136: (-DPARALLEL_MARK, or --enable-parallel-mark).
! 137: <P>
! 138: If the collector is used in an environment in which pointer location
! 139: information for heap objects is easily available, this can be passed on
! 140: to the colllector using the interfaces in either <TT>gc_typed.h</tt>
! 141: or <TT>gc_gcj.h</tt>.
! 142: <P>
! 143: The collector distribution also includes a <B>string package</b> that takes
! 144: advantage of the collector. For details see
! 145: <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/cordh.txt">cord.h</a>
! 146:
! 147: <H1>C++ Interface</h1>
! 148: There are three distinct ways to use the collector from C++:
! 149: <DL>
! 150: <DT> <B> STL allocators </b>
! 151: <DD>
! 152: Users of the <A HREF="http://www.sgi.com/tech/stl">SGI extended STL</a>
! 153: can include <TT>new_gc_alloc.h</tt> before including
! 154: STL header files.
! 155: (<TT>gc_alloc.h</tt> corresponds to now obsolete versions of the
! 156: SGI STL.)
! 157: This defines SGI-style allocators
! 158: <UL>
! 159: <LI> alloc
! 160: <LI> single_client_alloc
! 161: <LI> gc_alloc
! 162: <LI> single_client_gc_alloc
! 163: </ul>
! 164: which may be used either directly to allocate memory or to instantiate
! 165: container templates. The first two allocate uncollectable but traced
! 166: memory, while the second two allocate collectable memory.
! 167: The single_client versions are not safe for concurrent access by
! 168: multiple threads, but are faster.
! 169: <P>
! 170: For an example, click <A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_alloc_exC.txt">here</a>.
! 171: <P>
! 172: Recent versions of the collector also include a more standard-conforming
! 173: allocator implemention in <TT>gc_allocator.h</tt>. It defines
! 174: <UL>
! 175: <LI> traceable_allocator
! 176: <LI> gc_allocator
! 177: </ul>
! 178: Again the former allocates uncollectable but traced memory.
! 179: This should work with any fully standard-conforming C++ compiler.
! 180: <DT> <B> Class inheritance based interface </b>
! 181: <DD>
! 182: Users may include gc_cpp.h and then cause members of certain classes to
! 183: be allocated in garbage collectable memory by inheriting from class gc.
! 184: For details see <A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gc_cpph.txt">gc_cpp.h</a>.
! 185: <DT> <B> C interface </b>
! 186: <DD>
! 187: It is also possible to use the C interface from
! 188: <A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a> directly.
! 189: On platforms which use malloc to implement ::new, it should usually be possible
! 190: to use a version of the collector that has been compiled as a malloc
! 191: replacement. It is also possible to replace ::new and other allocation
! 192: functions suitably.
! 193: <P>
! 194: Note that user-implemented small-block allocation often works poorly with
! 195: an underlying garbage-collected large block allocator, since the collector
! 196: has to view all objects accessible from the user's free list as reachable.
! 197: This is likely to cause problems if GC_malloc is used with something like
! 198: the original HP version of STL.
! 199: This approach works with the SGI versions of the STL only if the
! 200: <TT>malloc_alloc</tt> allocator is used.
! 201: </dl>
! 202: </body>
! 203: </html>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to gcinterface.html CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM_contrib2 / asir2000 / gc / doc