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

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