aboutsummaryrefslogtreecommitdiffstats
path: root/gc/doc/gcinterface.html
diff options
context:
space:
mode:
Diffstat (limited to 'gc/doc/gcinterface.html')
-rw-r--r--gc/doc/gcinterface.html203
1 files changed, 0 insertions, 203 deletions
diff --git a/gc/doc/gcinterface.html b/gc/doc/gcinterface.html
deleted file mode 100644
index 7b336ec811b..00000000000
--- a/gc/doc/gcinterface.html
+++ /dev/null
@@ -1,203 +0,0 @@
1<!DOCTYPE HTML>
2<HEAD>
3<TITLE>Garbage Collector Interface</TITLE>
4</HEAD>
5<BODY>
6<H1>C Interface</h1>
7On many platforms, a single-threaded garbage collector library can be built
8to act as a plug-in malloc replacement. (Build with -DREDIRECT_MALLOC=GC_malloc
9-DIGNORE_FREE.) This is often the best way to deal with third-party libraries
10which leak or prematurely free objects. -DREDIRECT_MALLOC is intended
11primarily as an easy way to adapt old code, not for new development.
12<P>
13New code should use the interface discussed below.
14<P>
15Code must be linked against the GC library. On most UNIX platforms,
16this will be gc.a.
17<P>
18The following describes the standard C interface to the garbage collector.
19It is not a complete definition of the interface. It describes only the
20most commonly used functionality, approximately in decreasing order of
21frequency of use. The description assumes an ANSI C compiler.
22The full interface is described in
23<A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a>
24or <TT>gc.h</tt> in the distribution.
25<P>
26Clients should include gc.h.
27<P>
28In the case of multithreaded code,
29gc.h should be included after the threads header file, and
30after defining the appropriate GC_XXXX_THREADS macro.
31(For 6.2alpha4 and later, simply defining GC_THREADS should suffice.)
32Gc.h must be included
33in files that use either GC or threads primitives, since threads primitives
34will be redefined to cooperate with the GC on many platforms.
35<DL>
36<DT> <B>void * GC_MALLOC(size_t <I>nbytes</i>)</b>
37<DD>
38Allocates and clears <I>nbytes</i> of storage.
39Requires (amortized) time proportional to <I>nbytes</i>.
40The resulting object will be automatically deallocated when unreferenced.
41References from objects allocated with the system malloc are usually not
42considered by the collector. (See GC_MALLOC_UNCOLLECTABLE, however.)
43GC_MALLOC is a macro which invokes GC_malloc by default or, if GC_DEBUG
44is defined before gc.h is included, a debugging version that checks
45occasionally for overwrite errors, and the like.
46<DT> <B>void * GC_MALLOC_ATOMIC(size_t <I>nbytes</i>)</b>
47<DD>
48Allocates <I>nbytes</i> of storage.
49Requires (amortized) time proportional to <I>nbytes</i>.
50The resulting object will be automatically deallocated when unreferenced.
51The client promises that the resulting object will never contain any pointers.
52The memory is not cleared.
53This is the preferred way to allocate strings, floating point arrays,
54bitmaps, etc.
55More precise information about pointer locations can be communicated to the
56collector using the interface in
57<A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gc_typedh.txt">gc_typed.h</a> in the distribution.
58<DT> <B>void * GC_MALLOC_UNCOLLECTABLE(size_t <I>nbytes</i>)</b>
59<DD>
60Identical to GC_MALLOC, except that the resulting object is not automatically
61deallocated. Unlike the system-provided malloc, the collector does
62scan the object for pointers to garbage-collectable memory, even if the
63block itself does not appear to be reachable. (Objects allocated in this way
64are effectively treated as roots by the collector.)
65<DT> <B> void * GC_REALLOC(void *old, size_t new_size) </b>
66<DD>
67Allocate a new object of the indicated size and copy (a prefix of) the
68old object into the new object. The old object is reused in place if
69convenient. If the original object was allocated with GC_malloc_atomic,
70the new object is subject to the same constraints. If it was allocated
71as an uncollectable object, then the new object is uncollectable, and
72the old object (if different) is deallocated.
73(Use GC_REALLOC with GC_MALLOC, etc.)
74<DT> <B> void GC_FREE(void *dead) </b>
75<DD>
76Explicitly deallocate an object. Typically not useful for small
77collectable objects. (Use GC_FREE with GC_MALLOC, etc.)
78<DT> <B> void * GC_MALLOC_IGNORE_OFF_PAGE(size_t <I>nbytes</i>) </b>
79<DD>
80<DT> <B> void * GC_MALLOC_ATOMIC_IGNORE_OFF_PAGE(size_t <I>nbytes</i>) </b>
81<DD>
82Analogous to GC_MALLOC and GC_MALLOC_ATOMIC, except that the client
83guarantees that as long
84as the resulting object is of use, a pointer is maintained to someplace
85inside the first 512 bytes of the object. This pointer should be declared
86volatile to avoid interference from compiler optimizations.
87(Other nonvolatile pointers to the object may exist as well.)
88This is the
89preferred way to allocate objects that are likely to be > 100KBytes in size.
90It greatly reduces the risk that such objects will be accidentally retained
91when they are no longer needed. Thus space usage may be significantly reduced.
92<DT> <B> void GC_gcollect(void) </b>
93<DD>
94Explicitly force a garbage collection.
95<DT> <B> void GC_enable_incremental(void) </b>
96<DD>
97Cause the garbage collector to perform a small amount of work
98every few invocations of GC_malloc or the like, instead of performing
99an entire collection at once. This is likely to increase total
100running time. It will improve response on a platform that either has
101suitable support in the garbage collector (Irix and most other Unix
102versions, win32 if the collector was suitably built) or if "stubborn"
103allocation is used (see <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a>).
104On many platforms this interacts poorly with system calls
105that write to the garbage collected heap.
106<DT> <B> GC_warn_proc GC_set_warn_proc(GC_warn_proc p) </b>
107<DD>
108Replace the default procedure used by the collector to print warnings.
109The collector
110may otherwise write to sterr, most commonly because GC_malloc was used
111in a situation in which GC_malloc_ignore_off_page would have been more
112appropriate. See <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a> for details.
113<DT> <B> void GC_register_finalizer(...) </b>
114<DD>
115Register a function to be called when an object becomes inaccessible.
116This is often useful as a backup method for releasing system resources
117(<I>e.g.</i> closing files) when the object referencing them becomes
118inaccessible.
119It is not an acceptable method to perform actions that must be performed
120in a timely fashion.
121See <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a> for details of the interface.
122See <A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/finalization.html">here</a> for a more detailed discussion
123of the design.
124<P>
125Note that an object may become inaccessible before client code is done
126operating on its fields. Suitable synchronization is usually required.
127See <A HREF="http://portal.acm.org/citation.cfm?doid=604131.604153">here</a>
128or <A HREF="http://www.hpl.hp.com/techreports/2002/HPL-2002-335.html">here</a>
129for details.
130</dl>
131<P>
132If you are concerned with multiprocessor performance and scalability,
133you should consider enabling and using thread local allocation (<I>e.g.</i>
134GC_LOCAL_MALLOC, see <TT>gc_local_alloc.h</tt>. If your platform
135supports it, you should build the collector with parallel marking support
136(-DPARALLEL_MARK, or --enable-parallel-mark).
137<P>
138If the collector is used in an environment in which pointer location
139information for heap objects is easily available, this can be passed on
140to the colllector using the interfaces in either <TT>gc_typed.h</tt>
141or <TT>gc_gcj.h</tt>.
142<P>
143The collector distribution also includes a <B>string package</b> that takes
144advantage of the collector. For details see
145<A HREF="http://www.hpl.hp.com/personal/Hans_Boehm/gc/gc_source/cordh.txt">cord.h</a>
146
147<H1>C++ Interface</h1>
148There are three distinct ways to use the collector from C++:
149<DL>
150<DT> <B> STL allocators </b>
151<DD>
152Users of the <A HREF="http://www.sgi.com/tech/stl">SGI extended STL</a>
153can include <TT>new_gc_alloc.h</tt> before including
154STL header files.
155(<TT>gc_alloc.h</tt> corresponds to now obsolete versions of the
156SGI STL.)
157This defines SGI-style allocators
158<UL>
159<LI> alloc
160<LI> single_client_alloc
161<LI> gc_alloc
162<LI> single_client_gc_alloc
163</ul>
164which may be used either directly to allocate memory or to instantiate
165container templates. The first two allocate uncollectable but traced
166memory, while the second two allocate collectable memory.
167The single_client versions are not safe for concurrent access by
168multiple threads, but are faster.
169<P>
170For an example, click <A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_alloc_exC.txt">here</a>.
171<P>
172Recent versions of the collector also include a more standard-conforming
173allocator implemention in <TT>gc_allocator.h</tt>. It defines
174<UL>
175<LI> traceable_allocator
176<LI> gc_allocator
177</ul>
178Again the former allocates uncollectable but traced memory.
179This should work with any fully standard-conforming C++ compiler.
180<DT> <B> Class inheritance based interface </b>
181<DD>
182Users may include gc_cpp.h and then cause members of certain classes to
183be allocated in garbage collectable memory by inheriting from class gc.
184For details see <A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gc_cpph.txt">gc_cpp.h</a>.
185<DT> <B> C interface </b>
186<DD>
187It is also possible to use the C interface from
188<A HREF="http://hpl.hp.com/personal/Hans_Boehm/gc/gc_source/gch.txt">gc.h</a> directly.
189On platforms which use malloc to implement ::new, it should usually be possible
190to use a version of the collector that has been compiled as a malloc
191replacement. It is also possible to replace ::new and other allocation
192functions suitably.
193<P>
194Note that user-implemented small-block allocation often works poorly with
195an underlying garbage-collected large block allocator, since the collector
196has to view all objects accessible from the user's free list as reachable.
197This is likely to cause problems if GC_malloc is used with something like
198the original HP version of STL.
199This approach works with the SGI versions of the STL only if the
200<TT>malloc_alloc</tt> allocator is used.
201</dl>
202</body>
203</html>
generated by cgit v1.2.1 (git 2.18.0) at 2026-04-17 18:58:23 +0000