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