← Back to branch summary

~ubuntu-branches/ubuntu/quantal/libgc/quantal

« back to all changes in this revision

Viewing changes to doc/gcinterface.html

  • Committer: Bazaar Package Importer
  • Author(s): Christoph Egger
  • Date: 2011-02-19 12:19:56 UTC
  • mfrom: (1.3.2 upstream) (0.1.5 experimental)
  • mto: This revision was merged to the branch mainline in revision 14.
  • Revision ID: james.westby@ubuntu.com-20110219121956-67rb69xlt5nud3v2
Tags: 1:7.1-5
Upload to unstable

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/gcinterface.html
106
106
<I>from the main executable, not from a dynamic library,</i> before
107
107
the initial invocation of a GC routine.  It is recommended that this be done
108
108
in portable code, though we try to ensure that it expands to a no-op
109
 
on as many platforms as possible.
 
109
on as many platforms as possible.  In GC 7.0, it was required if
 
110
thread-local allocation is enabled in the collector build, and <TT>malloc</tt>
 
111
is not redirected to <TT>GC_malloc</tt>.
110
112
<DT> <B> void GC_gcollect(void) </b>
111
113
<DD>
112
114
Explicitly force a garbage collection.
165
167
<A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/cordh.txt">cord.h</a>
166
168
 
167
169
<H1>C++ Interface</h1>
168
 
Usage of the collector from C++ is complicated by the fact that there
 
170
The C++ interface is implemented as a thin layer on the C interface.
 
171
Unfortunately, this thin layer appears to be very sensitive to variations
 
172
in C++ implementations, particularly since it tries to replace the global
 
173
::new operator, something that appears to not be well-standardized.
 
174
Your platform may need minor adjustments in this layer (gc_cpp.cc, gc_cpp.h,
 
175
and possibly gc_allocator.h).  Such changes do not require understanding
 
176
of collector internals, though they may require a good understanding of
 
177
your platform.  (Patches enhancing portability are welcome.
 
178
But it's easy to break one platform by fixing another.)
 
179
<P>
 
180
Usage of the collector from C++ is also complicated by the fact that there
169
181
are many "standard" ways to allocate memory in C++.  The default ::new
170
182
operator, default malloc, and default STL allocators allocate memory
171
183
that is not garbage collected, and is not normally "traced" by the
183
195
</ul>
184
196
"Traceable" objects are not necessarily reclaimed by the collector,
185
197
but are scanned for pointers to collectable objects.
186
 
They are allocated by <TT>GC_MALLOC_UNCOLLECTABLE</tt>, as described
 
198
They are usually allocated by <TT>GC_MALLOC_UNCOLLECTABLE</tt>, as described
187
199
above, and through some interfaces described below.
188
200
<P>
189
201
(On most platforms, the collector may not trace correctly from in-flight
194
206
The easiest way to ensure that collectable objects are properly referenced
195
207
is to allocate only collectable objects.  This requires that every
196
208
allocation go through one of the following interfaces, each one of
197
 
which replaces a standard C++ allocation mechanism:
 
209
which replaces a standard C++ allocation mechanism.  Note that
 
210
this requires that all STL containers be explicitly instantiated with
 
211
<TT>gc_allocator</tt>.
198
212
<DL>
199
213
<DT> <B> STL allocators </b>
200
214
<DD>
 
215
<P>
 
216
Recent versions of the collector include a hopefully standard-conforming
 
217
allocator implementation in <TT>gc_allocator.h</tt>.  It defines
 
218
<UL>
 
219
<LI> <TT>traceable_allocator</tt>
 
220
<LI> <TT>gc_allocator</tt>
 
221
</ul>
 
222
which may be used either directly to allocate memory or to instantiate
 
223
container templates. 
 
224
The former allocates uncollectable but traced memory.
 
225
The latter allocates garbage-collected memory.
 
226
<P>
 
227
These should work with any fully standard-conforming C++ compiler.
 
228
<P>
201
229
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.
 
230
or its derivatives (including most g++ versions)
 
231
may instead be able to include <TT>new_gc_alloc.h</tt> before including
 
232
STL header files.  This is increasingly discouraged.
204
233
(<TT>gc_alloc.h</tt> corresponds to now obsolete versions of the
205
 
SGI STL.)
 
234
SGI STL.)  This interface is no longer recommended, but it has existed
 
235
for much longer.
 
236
<P>
206
237
This defines SGI-style allocators
207
238
<UL>
208
 
<LI> alloc
209
 
<LI> single_client_alloc
210
 
<LI> gc_alloc
211
 
<LI> single_client_gc_alloc
 
239
<LI> <TT>alloc</tt>
 
240
<LI> <TT>single_client_alloc</tt>
 
241
<LI> <TT>gc_alloc</tt>
 
242
<LI> <TT>single_client_gc_alloc</tt>
212
243
</ul>
213
 
which may be used either directly to allocate memory or to instantiate
214
 
container templates.  The first two allocate uncollectable but traced
 
244
The first two allocate uncollectable but traced
215
245
memory, while the second two allocate collectable memory.
216
 
The single_client versions are not safe for concurrent access by
 
246
The <TT>single_client</tt> versions are not safe for concurrent access by
217
247
multiple threads, but are faster.
218
248
<P>
219
249
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>
 
250
<DT> <B> Class inheritance based interface for new-based allocation</b>
230
251
<DD>
231
252
Users may include gc_cpp.h and then cause members of classes to
232
253
be allocated in garbage collectable memory by having those classes