]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | #ifndef GC_CPP_H |
2 | #define GC_CPP_H | |
3 | /**************************************************************************** | |
4 | Copyright (c) 1994 by Xerox Corporation. All rights reserved. | |
5 | ||
6 | THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED | |
7 | OR IMPLIED. ANY USE IS AT YOUR OWN RISK. | |
8 | ||
9 | Permission is hereby granted to use or copy this program for any | |
10 | purpose, provided the above notices are retained on all copies. | |
11 | Permission to modify the code and to distribute modified code is | |
12 | granted, provided the above notices are retained, and a notice that | |
13 | the code was modified is included with the above copyright notice. | |
14 | **************************************************************************** | |
15 | ||
16 | C++ Interface to the Boehm Collector | |
17 | ||
18 | John R. Ellis and Jesse Hull | |
19 | ||
20 | This interface provides access to the Boehm collector. It provides | |
21 | basic facilities similar to those described in "Safe, Efficient | |
22 | Garbage Collection for C++", by John R. Elis and David L. Detlefs | |
23 | (ftp://ftp.parc.xerox.com/pub/ellis/gc). | |
24 | ||
25 | All heap-allocated objects are either "collectable" or | |
26 | "uncollectable". Programs must explicitly delete uncollectable | |
27 | objects, whereas the garbage collector will automatically delete | |
28 | collectable objects when it discovers them to be inaccessible. | |
29 | Collectable objects may freely point at uncollectable objects and vice | |
30 | versa. | |
31 | ||
32 | Objects allocated with the built-in "::operator new" are uncollectable. | |
33 | ||
34 | Objects derived from class "gc" are collectable. For example: | |
35 | ||
36 | class A: public gc {...}; | |
37 | A* a = new A; // a is collectable. | |
38 | ||
39 | Collectable instances of non-class types can be allocated using the GC | |
40 | (or UseGC) placement: | |
41 | ||
42 | typedef int A[ 10 ]; | |
43 | A* a = new (GC) A; | |
44 | ||
45 | Uncollectable instances of classes derived from "gc" can be allocated | |
46 | using the NoGC placement: | |
47 | ||
48 | class A: public gc {...}; | |
49 | A* a = new (NoGC) A; // a is uncollectable. | |
50 | ||
51 | The new(PointerFreeGC) syntax allows the allocation of collectable | |
52 | objects that are not scanned by the collector. This useful if you | |
53 | are allocating compressed data, bitmaps, or network packets. (In | |
54 | the latter case, it may remove danger of unfriendly network packets | |
55 | intentionally containing values that cause spurious memory retention.) | |
56 | ||
57 | Both uncollectable and collectable objects can be explicitly deleted | |
58 | with "delete", which invokes an object's destructors and frees its | |
59 | storage immediately. | |
60 | ||
61 | A collectable object may have a clean-up function, which will be | |
62 | invoked when the collector discovers the object to be inaccessible. | |
63 | An object derived from "gc_cleanup" or containing a member derived | |
64 | from "gc_cleanup" has a default clean-up function that invokes the | |
65 | object's destructors. Explicit clean-up functions may be specified as | |
66 | an additional placement argument: | |
67 | ||
68 | A* a = ::new (GC, MyCleanup) A; | |
69 | ||
70 | An object is considered "accessible" by the collector if it can be | |
71 | reached by a path of pointers from static variables, automatic | |
72 | variables of active functions, or from some object with clean-up | |
73 | enabled; pointers from an object to itself are ignored. | |
74 | ||
75 | Thus, if objects A and B both have clean-up functions, and A points at | |
76 | B, B is considered accessible. After A's clean-up is invoked and its | |
77 | storage released, B will then become inaccessible and will have its | |
78 | clean-up invoked. If A points at B and B points to A, forming a | |
79 | cycle, then that's considered a storage leak, and neither will be | |
80 | collectable. See the interface gc.h for low-level facilities for | |
81 | handling such cycles of objects with clean-up. | |
82 | ||
83 | The collector cannot guarantee that it will find all inaccessible | |
84 | objects. In practice, it finds almost all of them. | |
85 | ||
86 | ||
87 | Cautions: | |
88 | ||
89 | 1. Be sure the collector has been augmented with "make c++" or | |
90 | "--enable-cplusplus". | |
91 | ||
92 | 2. If your compiler supports the new "operator new[]" syntax, then | |
93 | add -DGC_OPERATOR_NEW_ARRAY to the Makefile. | |
94 | ||
95 | If your compiler doesn't support "operator new[]", beware that an | |
96 | array of type T, where T is derived from "gc", may or may not be | |
97 | allocated as a collectable object (it depends on the compiler). Use | |
98 | the explicit GC placement to make the array collectable. For example: | |
99 | ||
100 | class A: public gc {...}; | |
101 | A* a1 = new A[ 10 ]; // collectable or uncollectable? | |
102 | A* a2 = new (GC) A[ 10 ]; // collectable | |
103 | ||
104 | 3. The destructors of collectable arrays of objects derived from | |
105 | "gc_cleanup" will not be invoked properly. For example: | |
106 | ||
107 | class A: public gc_cleanup {...}; | |
108 | A* a = new (GC) A[ 10 ]; // destructors not invoked correctly | |
109 | ||
110 | Typically, only the destructor for the first element of the array will | |
111 | be invoked when the array is garbage-collected. To get all the | |
112 | destructors of any array executed, you must supply an explicit | |
113 | clean-up function: | |
114 | ||
115 | A* a = new (GC, MyCleanUp) A[ 10 ]; | |
116 | ||
117 | (Implementing clean-up of arrays correctly, portably, and in a way | |
118 | that preserves the correct exception semantics requires a language | |
119 | extension, e.g. the "gc" keyword.) | |
120 | ||
121 | 4. Compiler bugs (now hopefully history): | |
122 | ||
123 | * Solaris 2's CC (SC3.0) doesn't implement t->~T() correctly, so the | |
124 | destructors of classes derived from gc_cleanup won't be invoked. | |
125 | You'll have to explicitly register a clean-up function with | |
126 | new-placement syntax. | |
127 | ||
128 | * Evidently cfront 3.0 does not allow destructors to be explicitly | |
129 | invoked using the ANSI-conforming syntax t->~T(). If you're using | |
130 | cfront 3.0, you'll have to comment out the class gc_cleanup, which | |
131 | uses explicit invocation. | |
132 | ||
133 | 5. GC name conflicts: | |
134 | ||
135 | Many other systems seem to use the identifier "GC" as an abbreviation | |
136 | for "Graphics Context". Since version 5.0, GC placement has been replaced | |
137 | by UseGC. GC is an alias for UseGC, unless GC_NAME_CONFLICT is defined. | |
138 | ||
139 | ****************************************************************************/ | |
140 | ||
141 | #include "gc.h" | |
142 | ||
143 | #ifndef THINK_CPLUS | |
144 | # define GC_cdecl | |
145 | #else | |
146 | # define GC_cdecl _cdecl | |
147 | #endif | |
148 | ||
149 | #if ! defined( GC_NO_OPERATOR_NEW_ARRAY ) \ | |
150 | && !defined(_ENABLE_ARRAYNEW) /* Digimars */ \ | |
151 | && (defined(__BORLANDC__) && (__BORLANDC__ < 0x450) \ | |
152 | || (defined(__GNUC__) && \ | |
153 | (__GNUC__ < 2 || __GNUC__ == 2 && __GNUC_MINOR__ < 6)) \ | |
154 | || (defined(__WATCOMC__) && __WATCOMC__ < 1050)) | |
155 | # define GC_NO_OPERATOR_NEW_ARRAY | |
156 | #endif | |
157 | ||
158 | #if !defined(GC_NO_OPERATOR_NEW_ARRAY) && !defined(GC_OPERATOR_NEW_ARRAY) | |
159 | # define GC_OPERATOR_NEW_ARRAY | |
160 | #endif | |
161 | ||
162 | #if ! defined ( __BORLANDC__ ) /* Confuses the Borland compiler. */ \ | |
163 | && ! defined ( __sgi ) | |
164 | # define GC_PLACEMENT_DELETE | |
165 | #endif | |
166 | ||
167 | enum GCPlacement {UseGC, | |
168 | #ifndef GC_NAME_CONFLICT | |
169 | GC=UseGC, | |
170 | #endif | |
171 | NoGC, PointerFreeGC}; | |
172 | ||
173 | class gc {public: | |
174 | inline void* operator new( size_t size ); | |
175 | inline void* operator new( size_t size, GCPlacement gcp ); | |
176 | inline void* operator new( size_t size, void *p ); | |
177 | /* Must be redefined here, since the other overloadings */ | |
178 | /* hide the global definition. */ | |
179 | inline void operator delete( void* obj ); | |
180 | # ifdef GC_PLACEMENT_DELETE | |
181 | inline void operator delete( void*, void* ); | |
182 | # endif | |
183 | ||
184 | #ifdef GC_OPERATOR_NEW_ARRAY | |
185 | inline void* operator new[]( size_t size ); | |
186 | inline void* operator new[]( size_t size, GCPlacement gcp ); | |
187 | inline void* operator new[]( size_t size, void *p ); | |
188 | inline void operator delete[]( void* obj ); | |
189 | # ifdef GC_PLACEMENT_DELETE | |
190 | inline void operator delete[]( void*, void* ); | |
191 | # endif | |
192 | #endif /* GC_OPERATOR_NEW_ARRAY */ | |
193 | }; | |
194 | /* | |
195 | Instances of classes derived from "gc" will be allocated in the | |
196 | collected heap by default, unless an explicit NoGC placement is | |
197 | specified. */ | |
198 | ||
199 | class gc_cleanup: virtual public gc {public: | |
200 | inline gc_cleanup(); | |
201 | inline virtual ~gc_cleanup(); | |
202 | private: | |
203 | inline static void GC_cdecl cleanup( void* obj, void* clientData );}; | |
204 | /* | |
205 | Instances of classes derived from "gc_cleanup" will be allocated | |
206 | in the collected heap by default. When the collector discovers an | |
207 | inaccessible object derived from "gc_cleanup" or containing a | |
208 | member derived from "gc_cleanup", its destructors will be | |
209 | invoked. */ | |
210 | ||
211 | extern "C" {typedef void (*GCCleanUpFunc)( void* obj, void* clientData );} | |
212 | ||
213 | #ifdef _MSC_VER | |
214 | // Disable warning that "no matching operator delete found; memory will | |
215 | // not be freed if initialization throws an exception" | |
216 | # pragma warning(disable:4291) | |
217 | #endif | |
218 | ||
219 | inline void* operator new( | |
220 | size_t size, | |
221 | GCPlacement gcp, | |
222 | GCCleanUpFunc cleanup = 0, | |
223 | void* clientData = 0 ); | |
224 | /* | |
225 | Allocates a collectable or uncollected object, according to the | |
226 | value of "gcp". | |
227 | ||
228 | For collectable objects, if "cleanup" is non-null, then when the | |
229 | allocated object "obj" becomes inaccessible, the collector will | |
230 | invoke the function "cleanup( obj, clientData )" but will not | |
231 | invoke the object's destructors. It is an error to explicitly | |
232 | delete an object allocated with a non-null "cleanup". | |
233 | ||
234 | It is an error to specify a non-null "cleanup" with NoGC or for | |
235 | classes derived from "gc_cleanup" or containing members derived | |
236 | from "gc_cleanup". */ | |
237 | ||
238 | ||
239 | #ifdef _MSC_VER | |
240 | /** This ensures that the system default operator new[] doesn't get | |
241 | * undefined, which is what seems to happen on VC++ 6 for some reason | |
242 | * if we define a multi-argument operator new[]. | |
243 | * There seems to be really redirect new in this environment without | |
244 | * including this everywhere. | |
245 | */ | |
246 | void *operator new[]( size_t size ); | |
247 | ||
248 | void operator delete[](void* obj); | |
249 | ||
250 | void* operator new( size_t size); | |
251 | ||
252 | void operator delete(void* obj); | |
253 | ||
254 | // This new operator is used by VC++ in case of Debug builds ! | |
255 | void* operator new( size_t size, | |
256 | int ,//nBlockUse, | |
257 | const char * szFileName, | |
258 | int nLine ); | |
259 | #endif /* _MSC_VER */ | |
260 | ||
261 | ||
262 | #ifdef GC_OPERATOR_NEW_ARRAY | |
263 | ||
264 | inline void* operator new[]( | |
265 | size_t size, | |
266 | GCPlacement gcp, | |
267 | GCCleanUpFunc cleanup = 0, | |
268 | void* clientData = 0 ); | |
269 | /* | |
270 | The operator new for arrays, identical to the above. */ | |
271 | ||
272 | #endif /* GC_OPERATOR_NEW_ARRAY */ | |
273 | ||
274 | /**************************************************************************** | |
275 | ||
276 | Inline implementation | |
277 | ||
278 | ****************************************************************************/ | |
279 | ||
280 | inline void* gc::operator new( size_t size ) { | |
281 | return GC_MALLOC( size );} | |
282 | ||
283 | inline void* gc::operator new( size_t size, GCPlacement gcp ) { | |
284 | if (gcp == UseGC) | |
285 | return GC_MALLOC( size ); | |
286 | else if (gcp == PointerFreeGC) | |
287 | return GC_MALLOC_ATOMIC( size ); | |
288 | else | |
289 | return GC_MALLOC_UNCOLLECTABLE( size );} | |
290 | ||
291 | inline void* gc::operator new( size_t size, void *p ) { | |
292 | return p;} | |
293 | ||
294 | inline void gc::operator delete( void* obj ) { | |
295 | GC_FREE( obj );} | |
296 | ||
297 | #ifdef GC_PLACEMENT_DELETE | |
298 | inline void gc::operator delete( void*, void* ) {} | |
299 | #endif | |
300 | ||
301 | #ifdef GC_OPERATOR_NEW_ARRAY | |
302 | ||
303 | inline void* gc::operator new[]( size_t size ) { | |
304 | return gc::operator new( size );} | |
305 | ||
306 | inline void* gc::operator new[]( size_t size, GCPlacement gcp ) { | |
307 | return gc::operator new( size, gcp );} | |
308 | ||
309 | inline void* gc::operator new[]( size_t size, void *p ) { | |
310 | return p;} | |
311 | ||
312 | inline void gc::operator delete[]( void* obj ) { | |
313 | gc::operator delete( obj );} | |
314 | ||
315 | #ifdef GC_PLACEMENT_DELETE | |
316 | inline void gc::operator delete[]( void*, void* ) {} | |
317 | #endif | |
318 | ||
319 | #endif /* GC_OPERATOR_NEW_ARRAY */ | |
320 | ||
321 | ||
322 | inline gc_cleanup::~gc_cleanup() { | |
323 | GC_register_finalizer_ignore_self( GC_base(this), 0, 0, 0, 0 );} | |
324 | ||
325 | inline void gc_cleanup::cleanup( void* obj, void* displ ) { | |
326 | ((gc_cleanup*) ((char*) obj + (ptrdiff_t) displ))->~gc_cleanup();} | |
327 | ||
328 | inline gc_cleanup::gc_cleanup() { | |
329 | GC_finalization_proc oldProc; | |
330 | void* oldData; | |
331 | void* base = GC_base( (void *) this ); | |
332 | if (0 != base) { | |
333 | // Don't call the debug version, since this is a real base address. | |
334 | GC_register_finalizer_ignore_self( | |
335 | base, (GC_finalization_proc)cleanup, (void*) ((char*) this - (char*) base), | |
336 | &oldProc, &oldData ); | |
337 | if (0 != oldProc) { | |
338 | GC_register_finalizer_ignore_self( base, oldProc, oldData, 0, 0 );}}} | |
339 | ||
340 | inline void* operator new( | |
341 | size_t size, | |
342 | GCPlacement gcp, | |
343 | GCCleanUpFunc cleanup, | |
344 | void* clientData ) | |
345 | { | |
346 | void* obj; | |
347 | ||
348 | if (gcp == UseGC) { | |
349 | obj = GC_MALLOC( size ); | |
350 | if (cleanup != 0) | |
351 | GC_REGISTER_FINALIZER_IGNORE_SELF( | |
352 | obj, cleanup, clientData, 0, 0 );} | |
353 | else if (gcp == PointerFreeGC) { | |
354 | obj = GC_MALLOC_ATOMIC( size );} | |
355 | else { | |
356 | obj = GC_MALLOC_UNCOLLECTABLE( size );}; | |
357 | return obj;} | |
358 | ||
359 | ||
360 | #ifdef GC_OPERATOR_NEW_ARRAY | |
361 | ||
362 | inline void* operator new[]( | |
363 | size_t size, | |
364 | GCPlacement gcp, | |
365 | GCCleanUpFunc cleanup, | |
366 | void* clientData ) | |
367 | { | |
368 | return ::operator new( size, gcp, cleanup, clientData );} | |
369 | ||
370 | #endif /* GC_OPERATOR_NEW_ARRAY */ | |
371 | ||
372 | ||
373 | #endif /* GC_CPP_H */ | |
374 |