src/mm/boehm-gc/doc/gcinterface.html

   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.
   9 (Build with <TT>-DREDIRECT_MALLOC=GC_malloc -DIGNORE_FREE</tt>.)
  10 This is often the best way to deal with third-party libraries
  11 which leak or prematurely free objects.  <TT>-DREDIRECT_MALLOC</tt> is intended
  12 primarily as an easy way to adapt old code, not for new development.
  13 <P>
  14 New code should use the interface discussed below.
  15 <P>
  16 Code must be linked against the GC library.  On most UNIX platforms,
  17 depending on how the collector is built, this will be <TT>gc.a</tt>
  18 or <TT>libgc.{a,so}</tt>.
  19 <P>
  20 The following describes the standard C interface to the garbage collector.
  21 It is not a complete definition of the interface.  It describes only the
  22 most commonly used functionality, approximately in decreasing order of
  23 frequency of use.
  24 The full interface is described in
  25 <A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a>
  26 or <TT>gc.h</tt> in the distribution.
  27 <P>
  28 Clients should include <TT>gc.h</tt>.
  29 <P>
  30 In the case of multithreaded code,
  31 <TT>gc.h</tt> should be included after the threads header file, and
  32 after defining the appropriate <TT>GC_</tt><I>XXXX</i><TT>_THREADS</tt> macro.
  33 (For 6.2alpha4 and later, simply defining <TT>GC_THREADS</tt> should suffice.)
  34 The header file <TT>gc.h</tt> must be included
  35 in files that use either GC or threads primitives, since threads primitives
  36 will be redefined to cooperate with the GC on many platforms.
  37 <P>
  38 Thread users should also be aware that on many platforms objects reachable
  39 only from thread-local variables may be prematurely reclaimed.
  40 Thus objects pointed to by thread-local variables should also be pointed to
  41 by a globally visible data structure.  (This is viewed as a bug, but as
  42 one that is exceedingly hard to fix without some libc hooks.)
  43 <DL>
  44 <DT> <B>void * GC_MALLOC(size_t <I>nbytes</i>)</b>
  45 <DD>
  46 Allocates and clears <I>nbytes</i> of storage.
  47 Requires (amortized) time proportional to <I>nbytes</i>.
  48 The resulting object will be automatically deallocated when unreferenced.
  49 References from objects allocated with the system malloc are usually not
  50 considered by the collector.  (See <TT>GC_MALLOC_UNCOLLECTABLE</tt>, however.)
  51 <TT>GC_MALLOC</tt> is a macro which invokes <TT>GC_malloc</tt> by default or,
  52 if <TT>GC_DEBUG</tt>
  53 is defined before <TT>gc.h</tt> is included, a debugging version that checks
  54 occasionally for overwrite errors, and the like.
  55 <DT> <B>void * GC_MALLOC_ATOMIC(size_t <I>nbytes</i>)</b>
  56 <DD>
  57 Allocates <I>nbytes</i> of storage.
  58 Requires (amortized) time proportional to <I>nbytes</i>.
  59 The resulting object will be automatically deallocated when unreferenced.
  60 The client promises that the resulting object will never contain any pointers.
  61 The memory is not cleared.
  62 This is the preferred way to allocate strings, floating point arrays,
  63 bitmaps, etc.
  64 More precise information about pointer locations can be communicated to the
  65 collector using the interface in
  66 <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gc_typedh.txt">gc_typed.h</a> in the distribution.
  67 <DT> <B>void * GC_MALLOC_UNCOLLECTABLE(size_t <I>nbytes</i>)</b>
  68 <DD>
  69 Identical to <TT>GC_MALLOC</tt>,
  70 except that the resulting object is not automatically
  71 deallocated.  Unlike the system-provided malloc, the collector does
  72 scan the object for pointers to garbage-collectable memory, even if the
  73 block itself does not appear to be reachable.  (Objects allocated in this way
  74 are effectively treated as roots by the collector.)
  75 <DT> <B> void * GC_REALLOC(void *<I>old</i>, size_t <I>new_size</i>) </b>
  76 <DD>
  77 Allocate a new object of the indicated size and copy (a prefix of) the
  78 old object into the new object.  The old object is reused in place if
  79 convenient.  If the original object was allocated with
  80 <TT>GC_MALLOC_ATOMIC</tt>,
  81 the new object is subject to the same constraints.  If it was allocated
  82 as an uncollectable object, then the new object is uncollectable, and
  83 the old object (if different) is deallocated.
  84 <DT> <B> void GC_FREE(void *<I>dead</i>) </b>
  85 <DD>
  86 Explicitly deallocate an object.  Typically not useful for small
  87 collectable objects.
  88 <DT> <B> void * GC_MALLOC_IGNORE_OFF_PAGE(size_t <I>nbytes</i>) </b>
  89 <DD>
  90 <DT> <B> void * GC_MALLOC_ATOMIC_IGNORE_OFF_PAGE(size_t <I>nbytes</i>) </b>
  91 <DD>
  92 Analogous to <TT>GC_MALLOC</tt> and <TT>GC_MALLOC_ATOMIC</tt>,
  93 except that the client
  94 guarantees that as long
  95 as the resulting object is of use, a pointer is maintained to someplace
  96 inside the first 512 bytes of the object.  This pointer should be declared
  97 volatile to avoid interference from compiler optimizations.
  98 (Other nonvolatile pointers to the object may exist as well.)
  99 This is the
 100 preferred way to allocate objects that are likely to be &gt; 100KBytes in size.
 101 It greatly reduces the risk that such objects will be accidentally retained
 102 when they are no longer needed.  Thus space usage may be significantly reduced.
 103 <DT> <B> void GC_INIT(void) </b>
 104 <DD>
 105 On some platforms, it is necessary to invoke this
 106 <I>from the main executable, not from a dynamic library,</i> before
 107 the initial invocation of a GC routine.  It is recommended that this be done
 108 in portable code, though we try to ensure that it expands to a no-op
 109 on as many platforms as possible.
 110 <DT> <B> void GC_gcollect(void) </b>
 111 <DD>
 112 Explicitly force a garbage collection.
 113 <DT> <B> void GC_enable_incremental(void) </b>
 114 <DD>
 115 Cause the garbage collector to perform a small amount of work
 116 every few invocations of <TT>GC_MALLOC</tt> or the like, instead of performing
 117 an entire collection at once.  This is likely to increase total
 118 running time.  It will improve response on a platform that either has
 119 suitable support in the garbage collector (Linux and most Unix
 120 versions, win32 if the collector was suitably built) or if "stubborn"
 121 allocation is used (see
 122 <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a>).
 123 On many platforms this interacts poorly with system calls
 124 that write to the garbage collected heap.
 125 <DT> <B> GC_warn_proc GC_set_warn_proc(GC_warn_proc <I>p</i>) </b>
 126 <DD>
 127 Replace the default procedure used by the collector to print warnings.
 128 The collector
 129 may otherwise write to sterr, most commonly because GC_malloc was used
 130 in a situation in which GC_malloc_ignore_off_page would have been more
 131 appropriate.  See <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a> for details.
 132 <DT> <B> void GC_REGISTER_FINALIZER(...) </b>
 133 <DD>
 134 Register a function to be called when an object becomes inaccessible.
 135 This is often useful as a backup method for releasing system resources
 136 (<I>e.g.</i> closing files) when the object referencing them becomes
 137 inaccessible.
 138 It is not an acceptable method to perform actions that must be performed
 139 in a timely fashion.
 140 See <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a> for details of the interface.
 141 See <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/finalization.html">here</a> for a more detailed discussion
 142 of the design.
 143 <P>
 144 Note that an object may become inaccessible before client code is done
 145 operating on objects referenced by its fields.
 146 Suitable synchronization is usually required.
 147 See <A HREF="http://portal.acm.org/citation.cfm?doid=604131.604153">here</a>
 148 or <A HREF="http://www.hpl.hp.com/techreports/2002/HPL-2002-335.html">here</a>
 149 for details.
 150 </dl>
 151 <P>
 152 If you are concerned with multiprocessor performance and scalability,
 153 you should consider enabling and using thread local allocation (<I>e.g.</i>
 154 <TT>GC_LOCAL_MALLOC</tt>, see <TT>gc_local_alloc.h</tt>.  If your platform
 155 supports it, you should build the collector with parallel marking support
 156 (<TT>-DPARALLEL_MARK</tt>, or <TT>--enable-parallel-mark</tt>).
 157 <P>
 158 If the collector is used in an environment in which pointer location
 159 information for heap objects is easily available, this can be passed on
 160 to the collector using the interfaces in either <TT>gc_typed.h</tt>
 161 or <TT>gc_gcj.h</tt>.
 162 <P>
 163 The collector distribution also includes a <B>string package</b> that takes
 164 advantage of the collector.  For details see
 165 <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/cordh.txt">cord.h</a>
 166
 167 <H1>C++ Interface</h1>
 168 Usage of the collector from C++ is complicated by the fact that there
 169 are many "standard" ways to allocate memory in C++.  The default ::new
 170 operator, default malloc, and default STL allocators allocate memory
 171 that is not garbage collected, and is not normally "traced" by the
 172 collector.  This means that any pointers in memory allocated by these
 173 default allocators will not be seen by the collector.  Garbage-collectable
 174 memory referenced only by pointers stored in such default-allocated
 175 objects is likely to be reclaimed prematurely by the collector.
 176 <P>
 177 It is the programmers responsibility to ensure that garbage-collectable
 178 memory is referenced by pointers stored in one of
 179 <UL>
 180 <LI> Program variables
 181 <LI> Garbage-collected objects
 182 <LI> Uncollected but "traceable" objects
 183 </ul>
 184 "Traceable" objects are not necessarily reclaimed by the collector,
 185 but are scanned for pointers to collectable objects.
 186 They are allocated by <TT>GC_MALLOC_UNCOLLECTABLE</tt>, as described
 187 above, and through some interfaces described below.
 188 <P>
 189 (On most platforms, the collector may not trace correctly from in-flight
 190 exception objects.  Thus objects thrown as exceptions should only
 191 point to otherwise reachable memory.  This is another bug whose
 192 proper repair requires platform hooks.)
 193 <P>
 194 The easiest way to ensure that collectable objects are properly referenced
 195 is to allocate only collectable objects.  This requires that every
 196 allocation go through one of the following interfaces, each one of
 197 which replaces a standard C++ allocation mechanism:
 198 <DL>
 199 <DT> <B> STL allocators </b>
 200 <DD>
 201 Users of the <A HREF="http://www.sgi.com/tech/stl">SGI extended STL</a>
 202 can include <TT>new_gc_alloc.h</tt> before including
 203 STL header files.
 204 (<TT>gc_alloc.h</tt> corresponds to now obsolete versions of the
 205 SGI STL.)
 206 This defines SGI-style allocators
 207 <UL>
 208 <LI> alloc
 209 <LI> single_client_alloc
 210 <LI> gc_alloc
 211 <LI> single_client_gc_alloc
 212 </ul>
 213 which may be used either directly to allocate memory or to instantiate
 214 container templates.  The first two allocate uncollectable but traced
 215 memory, while the second two allocate collectable memory.
 216 The single_client versions are not safe for concurrent access by
 217 multiple threads, but are faster.
 218 <P>
 219 For an example, click <A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_alloc_exC.txt">here</a>.
 220 <P>
 221 Recent versions of the collector also include a more standard-conforming
 222 allocator implementation in <TT>gc_allocator.h</tt>.  It defines
 223 <UL>
 224 <LI> traceable_allocator
 225 <LI> gc_allocator
 226 </ul>
 227 Again the former allocates uncollectable but traced memory.
 228 This should work with any fully standard-conforming C++ compiler.
 229 <DT> <B> Class inheritance based interface </b>
 230 <DD>
 231 Users may include gc_cpp.h and then cause members of classes to
 232 be allocated in garbage collectable memory by having those classes
 233 inherit from class gc.
 234 For details see <A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gc_cpph.txt">gc_cpp.h</a>.
 235 <P>
 236 Linking against libgccpp in addition to the gc library overrides
 237 ::new (and friends) to allocate traceable memory but uncollectable
 238 memory, making it safe to refer to collectable objects from the resulting
 239 memory.
 240 <DT> <B> C interface </b>
 241 <DD>
 242 It is also possible to use the C interface from
 243 <A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a> directly.
 244 On platforms which use malloc to implement ::new, it should usually be possible
 245 to use a version of the collector that has been compiled as a malloc
 246 replacement.  It is also possible to replace ::new and other allocation
 247 functions suitably, as is done by libgccpp.
 248 <P>
 249 Note that user-implemented small-block allocation often works poorly with
 250 an underlying garbage-collected large block allocator, since the collector
 251 has to view all objects accessible from the user's free list as reachable.
 252 This is likely to cause problems if <TT>GC_MALLOC</tt>
 253 is used with something like
 254 the original HP version of STL.
 255 This approach works well with the SGI versions of the STL only if the
 256 <TT>malloc_alloc</tt> allocator is used.
 257 </dl>
 258 </body>
 259 </html>