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