gc-7.2/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 stderr, 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 <P>
 162 If your platform
 163 supports it, you should build the collector with parallel marking support
 164 (<TT>-DPARALLEL_MARK</tt>, or <TT>--enable-parallel-mark</tt>).
 165 <P>
 166 If the collector is used in an environment in which pointer location
 167 information for heap objects is easily available, this can be passed on
 168 to the collector using the interfaces in either <TT>gc_typed.h</tt>
 169 or <TT>gc_gcj.h</tt>.
 170 <P>
 171 The collector distribution also includes a <B>string package</b> that takes
 172 advantage of the collector.  For details see
 173 <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/cordh.txt">cord.h</a>
 174
 175 <H1>C++ Interface</h1>
 176 The C++ interface is implemented as a thin layer on the C interface.
 177 Unfortunately, this thin layer appears to be very sensitive to variations
 178 in C++ implementations, particularly since it tries to replace the global
 179 ::new operator, something that appears to not be well-standardized.
 180 Your platform may need minor adjustments in this layer (gc_cpp.cc, gc_cpp.h,
 181 and possibly gc_allocator.h).  Such changes do not require understanding
 182 of collector internals, though they may require a good understanding of
 183 your platform.  (Patches enhancing portability are welcome.
 184 But it's easy to break one platform by fixing another.)
 185 <P>
 186 Usage of the collector from C++ is also complicated by the fact that there
 187 are many "standard" ways to allocate memory in C++.  The default ::new
 188 operator, default malloc, and default STL allocators allocate memory
 189 that is not garbage collected, and is not normally "traced" by the
 190 collector.  This means that any pointers in memory allocated by these
 191 default allocators will not be seen by the collector.  Garbage-collectable
 192 memory referenced only by pointers stored in such default-allocated
 193 objects is likely to be reclaimed prematurely by the collector.
 194 <P>
 195 It is the programmers responsibility to ensure that garbage-collectable
 196 memory is referenced by pointers stored in one of
 197 <UL>
 198 <LI> Program variables
 199 <LI> Garbage-collected objects
 200 <LI> Uncollected but "traceable" objects
 201 </ul>
 202 "Traceable" objects are not necessarily reclaimed by the collector,
 203 but are scanned for pointers to collectable objects.
 204 They are usually allocated by <TT>GC_MALLOC_UNCOLLECTABLE</tt>, as described
 205 above, and through some interfaces described below.
 206 <P>
 207 (On most platforms, the collector may not trace correctly from in-flight
 208 exception objects.  Thus objects thrown as exceptions should only
 209 point to otherwise reachable memory.  This is another bug whose
 210 proper repair requires platform hooks.)
 211 <P>
 212 The easiest way to ensure that collectable objects are properly referenced
 213 is to allocate only collectable objects.  This requires that every
 214 allocation go through one of the following interfaces, each one of
 215 which replaces a standard C++ allocation mechanism.  Note that
 216 this requires that all STL containers be explicitly instantiated with
 217 <TT>gc_allocator</tt>.
 218 <DL>
 219 <DT> <B> STL allocators </b>
 220 <DD>
 221 <P>
 222 Recent versions of the collector include a hopefully standard-conforming
 223 allocator implementation in <TT>gc_allocator.h</tt>.  It defines
 224 <UL>
 225 <LI> <TT>traceable_allocator</tt>
 226 <LI> <TT>gc_allocator</tt>
 227 </ul>
 228 which may be used either directly to allocate memory or to instantiate
 229 container templates.
 230 The former allocates uncollectable but traced memory.
 231 The latter allocates garbage-collected memory.
 232 <P>
 233 These should work with any fully standard-conforming C++ compiler.
 234 <P>
 235 Users of the <A HREF="http://www.sgi.com/tech/stl">SGI extended STL</a>
 236 or its derivatives (including most g++ versions)
 237 may instead be able to include <TT>new_gc_alloc.h</tt> before including
 238 STL header files.  This is increasingly discouraged.
 239 <P>
 240 This defines SGI-style allocators
 241 <UL>
 242 <LI> <TT>alloc</tt>
 243 <LI> <TT>single_client_alloc</tt>
 244 <LI> <TT>gc_alloc</tt>
 245 <LI> <TT>single_client_gc_alloc</tt>
 246 </ul>
 247 The first two allocate uncollectable but traced
 248 memory, while the second two allocate collectable memory.
 249 The <TT>single_client</tt> versions are not safe for concurrent access by
 250 multiple threads, but are faster.
 251 <P>
 252 For an example, click <A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_alloc_exC.txt">here</a>.
 253 <DT> <B> Class inheritance based interface for new-based allocation</b>
 254 <DD>
 255 Users may include gc_cpp.h and then cause members of classes to
 256 be allocated in garbage collectable memory by having those classes
 257 inherit from class gc.
 258 For details see <A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gc_cpph.txt">gc_cpp.h</a>.
 259 <P>
 260 Linking against libgccpp in addition to the gc library overrides
 261 ::new (and friends) to allocate traceable memory but uncollectable
 262 memory, making it safe to refer to collectable objects from the resulting
 263 memory.
 264 <DT> <B> C interface </b>
 265 <DD>
 266 It is also possible to use the C interface from
 267 <A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a> directly.
 268 On platforms which use malloc to implement ::new, it should usually be possible
 269 to use a version of the collector that has been compiled as a malloc
 270 replacement.  It is also possible to replace ::new and other allocation
 271 functions suitably, as is done by libgccpp.
 272 <P>
 273 Note that user-implemented small-block allocation often works poorly with
 274 an underlying garbage-collected large block allocator, since the collector
 275 has to view all objects accessible from the user's free list as reachable.
 276 This is likely to cause problems if <TT>GC_MALLOC</tt>
 277 is used with something like
 278 the original HP version of STL.
 279 This approach works well with the SGI versions of the STL only if the
 280 <TT>malloc_alloc</tt> allocator is used.
 281 </dl>
 282 </body>
 283 </html>