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