| 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 > 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>
|
|---|
