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