<I>from the main executable, not from a dynamic library,</i> before
the initial invocation of a GC routine. It is recommended that this be done
in portable code, though we try to ensure that it expands to a no-op
-on as many platforms as possible. As of GC 7.0, it is required if
+on as many platforms as possible. In GC 7.0, it was required if
thread-local allocation is enabled in the collector build, and <TT>malloc</tt>
is not redirected to <TT>GC_malloc</tt>.
<DT> <B> void GC_gcollect(void) </b>
The easiest way to ensure that collectable objects are properly referenced
is to allocate only collectable objects. This requires that every
allocation go through one of the following interfaces, each one of
-which replaces a standard C++ allocation mechanism:
+which replaces a standard C++ allocation mechanism. Note that
+this requires that all STL containers be explicitly instantiated with
+<TT>gc_allocator</tt>.
<DL>
<DT> <B> STL allocators </b>
<DD>
<P>
-Recent versions of the collector also include a more standard-conforming
+Recent versions of the collector include a hopefully standard-conforming
allocator implementation in <TT>gc_allocator.h</tt>. It defines
<UL>
-<LI> traceable_allocator
-<LI> gc_allocator
+<LI> <TT>traceable_allocator</tt>
+<LI> <TT>gc_allocator</tt>
</ul>
which may be used either directly to allocate memory or to instantiate
container templates.
<P>
Users of the <A HREF="http://www.sgi.com/tech/stl">SGI extended STL</a>
or its derivatives (including most g++ versions)
-can alternatively include <TT>new_gc_alloc.h</tt> before including
-STL header files.
+may instead be able to include <TT>new_gc_alloc.h</tt> before including
+STL header files. This is increasingly discouraged.
(<TT>gc_alloc.h</tt> corresponds to now obsolete versions of the
SGI STL.) This interface is no longer recommended, but it has existed
for much longer.
<P>
This defines SGI-style allocators
<UL>
-<LI> alloc
-<LI> single_client_alloc
-<LI> gc_alloc
-<LI> single_client_gc_alloc
+<LI> <TT>alloc</tt>
+<LI> <TT>single_client_alloc</tt>
+<LI> <TT>gc_alloc</tt>
+<LI> <TT>single_client_gc_alloc</tt>
</ul>
The first two allocate uncollectable but traced
memory, while the second two allocate collectable memory.
-The single_client versions are not safe for concurrent access by
+The <TT>single_client</tt> versions are not safe for concurrent access by
multiple threads, but are faster.
<P>
For an example, click <A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_alloc_exC.txt">here</a>.
-<DT> <B> Class inheritance based interface </b>
+<DT> <B> Class inheritance based interface for new-based allocation</b>
<DD>
Users may include gc_cpp.h and then cause members of classes to
be allocated in garbage collectable memory by having those classes