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.  In GC 7.0, it was required if
 110 thread-local allocation is enabled in the collector build, and <TT>malloc</tt>
 111 is not redirected to <TT>GC_malloc</tt>.
 112 <DT> <B> void GC_gcollect(void) </b>
 113 <DD>
 114 Explicitly force a garbage collection.
 115 <DT> <B> void GC_enable_incremental(void) </b>
 116 <DD>
 117 Cause the garbage collector to perform a small amount of work
 118 every few invocations of <TT>GC_MALLOC</tt> or the like, instead of performing
 119 an entire collection at once.  This is likely to increase total
 120 running time.  It will improve response on a platform that either has
 121 suitable support in the garbage collector (Linux and most Unix
 122 versions, win32 if the collector was suitably built) or if "stubborn"
 123 allocation is used (see
 124 <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a>).
 125 On many platforms this interacts poorly with system calls
 126 that write to the garbage collected heap.
 127 <DT> <B> GC_warn_proc GC_set_warn_proc(GC_warn_proc <I>p</i>) </b>
 128 <DD>
 129 Replace the default procedure used by the collector to print warnings.
 130 The collector
 131 may otherwise write to sterr, most commonly because GC_malloc was used
 132 in a situation in which GC_malloc_ignore_off_page would have been more
 133 appropriate.  See <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a> for details.
 134 <DT> <B> void GC_REGISTER_FINALIZER(...) </b>
 135 <DD>
 136 Register a function to be called when an object becomes inaccessible.
 137 This is often useful as a backup method for releasing system resources
 138 (<I>e.g.</i> closing files) when the object referencing them becomes
 139 inaccessible.
 140 It is not an acceptable method to perform actions that must be performed
 141 in a timely fashion.
 142 See <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a> for details of the interface.
 143 See <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/finalization.html">here</a> for a more detailed discussion
 144 of the design.
 145 <P>
 146 Note that an object may become inaccessible before client code is done
 147 operating on objects referenced by its fields.
 148 Suitable synchronization is usually required.
 149 See <A HREF="http://portal.acm.org/citation.cfm?doid=604131.604153">here</a>
 150 or <A HREF="http://www.hpl.hp.com/techreports/2002/HPL-2002-335.html">here</a>
 151 for details.
 152 </dl>
 153 <P>
 154 If you are concerned with multiprocessor performance and scalability,
 155 you should consider enabling and using thread local allocation (<I>e.g.</i>
 156 <TT>GC_LOCAL_MALLOC</tt>, see <TT>gc_local_alloc.h</tt>.  If your platform
 157 supports it, you should build the collector with parallel marking support
 158 (<TT>-DPARALLEL_MARK</tt>, or <TT>--enable-parallel-mark</tt>).
 159 <P>
 160 If the collector is used in an environment in which pointer location
 161 information for heap objects is easily available, this can be passed on
 162 to the collector using the interfaces in either <TT>gc_typed.h</tt>
 163 or <TT>gc_gcj.h</tt>.
 164 <P>
 165 The collector distribution also includes a <B>string package</b> that takes
 166 advantage of the collector.  For details see
 167 <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/cordh.txt">cord.h</a>
 168
 169 <H1>C++ Interface</h1>
 170 The C++ interface is implemented as a thin layer on the C interface.
 171 Unfortunately, this thin layer appears to be very sensitive to variations
 172 in C++ implementations, particularly since it tries to replace the global
 173 ::new operator, something that appears to not be well-standardized.
 174 Your platform may need minor adjustments in this layer (gc_cpp.cc, gc_cpp.h,
 175 and possibly gc_allocator.h).  Such changes do not require understanding
 176 of collector internals, though they may require a good understanding of
 177 your platform.  (Patches enhancing portability are welcome.
 178 But it's easy to break one platform by fixing another.)
 179 <P>
 180 Usage of the collector from C++ is also complicated by the fact that there
 181 are many "standard" ways to allocate memory in C++.  The default ::new
 182 operator, default malloc, and default STL allocators allocate memory
 183 that is not garbage collected, and is not normally "traced" by the
 184 collector.  This means that any pointers in memory allocated by these
 185 default allocators will not be seen by the collector.  Garbage-collectable
 186 memory referenced only by pointers stored in such default-allocated
 187 objects is likely to be reclaimed prematurely by the collector.
 188 <P>
 189 It is the programmers responsibility to ensure that garbage-collectable
 190 memory is referenced by pointers stored in one of
 191 <UL>
 192 <LI> Program variables
 193 <LI> Garbage-collected objects
 194 <LI> Uncollected but "traceable" objects
 195 </ul>
 196 "Traceable" objects are not necessarily reclaimed by the collector,
 197 but are scanned for pointers to collectable objects.
 198 They are usually allocated by <TT>GC_MALLOC_UNCOLLECTABLE</tt>, as described
 199 above, and through some interfaces described below.
 200 <P>
 201 (On most platforms, the collector may not trace correctly from in-flight
 202 exception objects.  Thus objects thrown as exceptions should only
 203 point to otherwise reachable memory.  This is another bug whose
 204 proper repair requires platform hooks.)
 205 <P>
 206 The easiest way to ensure that collectable objects are properly referenced
 207 is to allocate only collectable objects.  This requires that every
 208 allocation go through one of the following interfaces, each one of
 209 which replaces a standard C++ allocation mechanism.  Note that
 210 this requires that all STL containers be explicitly instantiated with
 211 <TT>gc_allocator</tt>.
 212 <DL>
 213 <DT> <B> STL allocators </b>
 214 <DD>
 215 <P>
 216 Recent versions of the collector include a hopefully standard-conforming
 217 allocator implementation in <TT>gc_allocator.h</tt>.  It defines
 218 <UL>
 219 <LI> <TT>traceable_allocator</tt>
 220 <LI> <TT>gc_allocator</tt>
 221 </ul>
 222 which may be used either directly to allocate memory or to instantiate
 223 container templates.
 224 The former allocates uncollectable but traced memory.
 225 The latter allocates garbage-collected memory.
 226 <P>
 227 These should work with any fully standard-conforming C++ compiler.
 228 <P>
 229 Users of the <A HREF="http://www.sgi.com/tech/stl">SGI extended STL</a>
 230 or its derivatives (including most g++ versions)
 231 may instead be able to include <TT>new_gc_alloc.h</tt> before including
 232 STL header files.  This is increasingly discouraged.
 233 (<TT>gc_alloc.h</tt> corresponds to now obsolete versions of the
 234 SGI STL.)  This interface is no longer recommended, but it has existed
 235 for much longer.
 236 <P>
 237 This defines SGI-style allocators
 238 <UL>
 239 <LI> <TT>alloc</tt>
 240 <LI> <TT>single_client_alloc</tt>
 241 <LI> <TT>gc_alloc</tt>
 242 <LI> <TT>single_client_gc_alloc</tt>
 243 </ul>
 244 The first two allocate uncollectable but traced
 245 memory, while the second two allocate collectable memory.
 246 The <TT>single_client</tt> versions are not safe for concurrent access by
 247 multiple threads, but are faster.
 248 <P>
 249 For an example, click <A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_alloc_exC.txt">here</a>.
 250 <DT> <B> Class inheritance based interface for new-based allocation</b>
 251 <DD>
 252 Users may include gc_cpp.h and then cause members of classes to
 253 be allocated in garbage collectable memory by having those classes
 254 inherit from class gc.
 255 For details see <A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gc_cpph.txt">gc_cpp.h</a>.
 256 <P>
 257 Linking against libgccpp in addition to the gc library overrides
 258 ::new (and friends) to allocate traceable memory but uncollectable
 259 memory, making it safe to refer to collectable objects from the resulting
 260 memory.
 261 <DT> <B> C interface </b>
 262 <DD>
 263 It is also possible to use the C interface from
 264 <A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a> directly.
 265 On platforms which use malloc to implement ::new, it should usually be possible
 266 to use a version of the collector that has been compiled as a malloc
 267 replacement.  It is also possible to replace ::new and other allocation
 268 functions suitably, as is done by libgccpp.
 269 <P>
 270 Note that user-implemented small-block allocation often works poorly with
 271 an underlying garbage-collected large block allocator, since the collector
 272 has to view all objects accessible from the user's free list as reachable.
 273 This is likely to cause problems if <TT>GC_MALLOC</tt>
 274 is used with something like
 275 the original HP version of STL.
 276 This approach works well with the SGI versions of the STL only if the
 277 <TT>malloc_alloc</tt> allocator is used.
 278 </dl>
 279 </body>
 280 </html>