3
<TITLE>Garbage Collector Interface</TITLE>
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.
14
New code should use the interface discussed below.
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>.
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
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.
28
Clients should include <TT>gc.h</tt>.
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.
38
<DT> <B>void * GC_MALLOC(size_t <I>nbytes</i>)</b>
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,
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>
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,
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>
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>
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>
80
Explicitly deallocate an object. Typically not useful for small
82
<DT> <B> void * GC_MALLOC_IGNORE_OFF_PAGE(size_t <I>nbytes</i>) </b>
84
<DT> <B> void * GC_MALLOC_ATOMIC_IGNORE_OFF_PAGE(size_t <I>nbytes</i>) </b>
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.)
94
preferred way to allocate objects that are likely to be > 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>
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>
106
Explicitly force a garbage collection.
107
<DT> <B> void GC_enable_incremental(void) </b>
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>
121
Replace the default procedure used by the collector to print warnings.
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>
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
132
It is not an acceptable method to perform actions that must be performed
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
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>
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>).
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>.
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>
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.
171
It is the programmers responsibility to ensure that garbage-collectable
172
memory is referenced by pointers stored in one of
174
<LI> Program variables
175
<LI> Garbage-collected objects
176
<LI> Uncollected but "traceable" objects
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.
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:
188
<DT> <B> STL allocators </b>
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
193
(<TT>gc_alloc.h</tt> corresponds to now obsolete versions of the
195
This defines SGI-style allocators
198
<LI> single_client_alloc
200
<LI> single_client_gc_alloc
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.
208
For an example, click <A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_alloc_exC.txt">here</a>.
210
Recent versions of the collector also include a more standard-conforming
211
allocator implementation in <TT>gc_allocator.h</tt>. It defines
213
<LI> traceable_allocator
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>
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>.
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
229
<DT> <B> C interface </b>
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.
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.
added
removed
src/gc/doc/gcinterface.html
