2 * Copyright (c) 1994 by Xerox Corporation. All rights reserved.
4 * THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
5 * OR IMPLIED. ANY USE IS AT YOUR OWN RISK.
7 * Permission is hereby granted to use or copy this program for any
8 * purpose, provided the above notices are retained on all copies.
9 * Permission to modify the code and to distribute modified code is
10 * granted, provided the above notices are retained, and a notice that
11 * the code was modified is included with the above copyright notice.
17 /****************************************************************************
18 C++ Interface to the Boehm Collector
20 John R. Ellis and Jesse Hull
22 This interface provides access to the Boehm collector. It provides
23 basic facilities similar to those described in "Safe, Efficient
24 Garbage Collection for C++", by John R. Elis and David L. Detlefs
25 (ftp://ftp.parc.xerox.com/pub/ellis/gc).
27 All heap-allocated objects are either "collectable" or
28 "uncollectable". Programs must explicitly delete uncollectable
29 objects, whereas the garbage collector will automatically delete
30 collectable objects when it discovers them to be inaccessible.
31 Collectable objects may freely point at uncollectable objects and vice
34 Objects allocated with the built-in "::operator new" are uncollectable.
36 Objects derived from class "gc" are collectable. For example:
38 class A: public gc {...};
39 A* a = new A; // a is collectable.
41 Collectable instances of non-class types can be allocated using the GC
47 Uncollectable instances of classes derived from "gc" can be allocated
48 using the NoGC placement:
50 class A: public gc {...};
51 A* a = new (NoGC) A; // a is uncollectable.
53 The new(PointerFreeGC) syntax allows the allocation of collectable
54 objects that are not scanned by the collector. This useful if you
55 are allocating compressed data, bitmaps, or network packets. (In
56 the latter case, it may remove danger of unfriendly network packets
57 intentionally containing values that cause spurious memory retention.)
59 Both uncollectable and collectable objects can be explicitly deleted
60 with "delete", which invokes an object's destructors and frees its
63 A collectable object may have a clean-up function, which will be
64 invoked when the collector discovers the object to be inaccessible.
65 An object derived from "gc_cleanup" or containing a member derived
66 from "gc_cleanup" has a default clean-up function that invokes the
67 object's destructors. Explicit clean-up functions may be specified as
68 an additional placement argument:
70 A* a = ::new (GC, MyCleanup) A;
72 An object is considered "accessible" by the collector if it can be
73 reached by a path of pointers from static variables, automatic
74 variables of active functions, or from some object with clean-up
75 enabled; pointers from an object to itself are ignored.
77 Thus, if objects A and B both have clean-up functions, and A points at
78 B, B is considered accessible. After A's clean-up is invoked and its
79 storage released, B will then become inaccessible and will have its
80 clean-up invoked. If A points at B and B points to A, forming a
81 cycle, then that's considered a storage leak, and neither will be
82 collectable. See the interface gc.h for low-level facilities for
83 handling such cycles of objects with clean-up.
85 The collector cannot guarantee that it will find all inaccessible
86 objects. In practice, it finds almost all of them.
91 1. Be sure the collector has been augmented with "make c++" or
94 2. If your compiler supports the new "operator new[]" syntax, then
95 add -DGC_OPERATOR_NEW_ARRAY to the Makefile.
97 If your compiler doesn't support "operator new[]", beware that an
98 array of type T, where T is derived from "gc", may or may not be
99 allocated as a collectable object (it depends on the compiler). Use
100 the explicit GC placement to make the array collectable. For example:
102 class A: public gc {...};
103 A* a1 = new A[ 10 ]; // collectable or uncollectable?
104 A* a2 = new (GC) A[ 10 ]; // collectable
106 3. The destructors of collectable arrays of objects derived from
107 "gc_cleanup" will not be invoked properly. For example:
109 class A: public gc_cleanup {...};
110 A* a = new (GC) A[ 10 ]; // destructors not invoked correctly
112 Typically, only the destructor for the first element of the array will
113 be invoked when the array is garbage-collected. To get all the
114 destructors of any array executed, you must supply an explicit
117 A* a = new (GC, MyCleanUp) A[ 10 ];
119 (Implementing clean-up of arrays correctly, portably, and in a way
120 that preserves the correct exception semantics requires a language
121 extension, e.g. the "gc" keyword.)
123 4. Compiler bugs (now hopefully history):
125 * Solaris 2's CC (SC3.0) doesn't implement t->~T() correctly, so the
126 destructors of classes derived from gc_cleanup won't be invoked.
127 You'll have to explicitly register a clean-up function with
128 new-placement syntax.
130 * Evidently cfront 3.0 does not allow destructors to be explicitly
131 invoked using the ANSI-conforming syntax t->~T(). If you're using
132 cfront 3.0, you'll have to comment out the class gc_cleanup, which
133 uses explicit invocation.
135 5. GC name conflicts:
137 Many other systems seem to use the identifier "GC" as an abbreviation
138 for "Graphics Context". Since version 5.0, GC placement has been replaced
139 by UseGC. GC is an alias for UseGC, unless GC_NAME_CONFLICT is defined.
141 ****************************************************************************/
146 # define GC_cdecl GC_CALLBACK
148 # define GC_cdecl _cdecl
151 #if ! defined( GC_NO_OPERATOR_NEW_ARRAY ) \
152 && !defined(_ENABLE_ARRAYNEW) /* Digimars */ \
153 && (defined(__BORLANDC__) && (__BORLANDC__ < 0x450) \
154 || (defined(__GNUC__) && \
155 (__GNUC__ < 2 || __GNUC__ == 2 && __GNUC_MINOR__ < 6)) \
156 || (defined(__WATCOMC__) && __WATCOMC__ < 1050))
157 # define GC_NO_OPERATOR_NEW_ARRAY
160 #if !defined(GC_NO_OPERATOR_NEW_ARRAY) && !defined(GC_OPERATOR_NEW_ARRAY)
161 # define GC_OPERATOR_NEW_ARRAY
164 #if ! defined ( __BORLANDC__ ) /* Confuses the Borland compiler. */ \
165 && ! defined ( __sgi ) && ! defined( __WATCOMC__ ) \
166 && (!defined(_MSC_VER) || _MSC_VER > 1020)
167 # define GC_PLACEMENT_DELETE
170 enum GCPlacement {UseGC,
171 #ifndef GC_NAME_CONFLICT
174 NoGC, PointerFreeGC};
177 inline void* operator new( size_t size );
178 inline void* operator new( size_t size, GCPlacement gcp );
179 inline void* operator new( size_t size, void *p );
180 /* Must be redefined here, since the other overloadings */
181 /* hide the global definition. */
182 inline void operator delete( void* obj );
183 # ifdef GC_PLACEMENT_DELETE
184 inline void operator delete( void*, GCPlacement );
185 /* called if construction fails. */
186 inline void operator delete( void*, void* );
189 #ifdef GC_OPERATOR_NEW_ARRAY
190 inline void* operator new[]( size_t size );
191 inline void* operator new[]( size_t size, GCPlacement gcp );
192 inline void* operator new[]( size_t size, void *p );
193 inline void operator delete[]( void* obj );
194 # ifdef GC_PLACEMENT_DELETE
195 inline void operator delete[]( void*, GCPlacement );
196 inline void operator delete[]( void*, void* );
198 #endif /* GC_OPERATOR_NEW_ARRAY */
201 Instances of classes derived from "gc" will be allocated in the
202 collected heap by default, unless an explicit NoGC placement is
205 class gc_cleanup: virtual public gc {public:
207 inline virtual ~gc_cleanup();
209 inline static void GC_cdecl cleanup( void* obj, void* clientData );};
211 Instances of classes derived from "gc_cleanup" will be allocated
212 in the collected heap by default. When the collector discovers an
213 inaccessible object derived from "gc_cleanup" or containing a
214 member derived from "gc_cleanup", its destructors will be
218 typedef void (GC_CALLBACK * GCCleanUpFunc)( void* obj, void* clientData );
222 // Disable warning that "no matching operator delete found; memory will
223 // not be freed if initialization throws an exception"
224 # pragma warning(disable:4291)
227 inline void* operator new(
230 GCCleanUpFunc cleanup = 0,
231 void* clientData = 0 );
233 Allocates a collectable or uncollected object, according to the
236 For collectable objects, if "cleanup" is non-null, then when the
237 allocated object "obj" becomes inaccessible, the collector will
238 invoke the function "cleanup( obj, clientData )" but will not
239 invoke the object's destructors. It is an error to explicitly
240 delete an object allocated with a non-null "cleanup".
242 It is an error to specify a non-null "cleanup" with NoGC or for
243 classes derived from "gc_cleanup" or containing members derived
244 from "gc_cleanup". */
246 # ifdef GC_PLACEMENT_DELETE
247 inline void operator delete( void*, GCPlacement, GCCleanUpFunc, void * );
251 /** This ensures that the system default operator new[] doesn't get
252 * undefined, which is what seems to happen on VC++ 6 for some reason
253 * if we define a multi-argument operator new[].
254 * There seems to be no way to redirect new in this environment without
255 * including this everywhere.
258 void *operator new[]( size_t size );
260 void operator delete[](void* obj);
263 void* operator new( size_t size);
265 void operator delete(void* obj);
267 // This new operator is used by VC++ in case of Debug builds !
268 void* operator new( size_t size,
270 const char * szFileName,
272 #endif /* _MSC_VER */
275 #ifdef GC_OPERATOR_NEW_ARRAY
277 inline void* operator new[](
280 GCCleanUpFunc cleanup = 0,
281 void* clientData = 0 );
283 The operator new for arrays, identical to the above. */
285 #endif /* GC_OPERATOR_NEW_ARRAY */
287 /****************************************************************************
289 Inline implementation
291 ****************************************************************************/
293 inline void* gc::operator new( size_t size ) {
294 return GC_MALLOC( size );}
296 inline void* gc::operator new( size_t size, GCPlacement gcp ) {
298 return GC_MALLOC( size );
299 else if (gcp == PointerFreeGC)
300 return GC_MALLOC_ATOMIC( size );
302 return GC_MALLOC_UNCOLLECTABLE( size );}
304 inline void* gc::operator new( size_t size, void *p ) {
307 inline void gc::operator delete( void* obj ) {
310 #ifdef GC_PLACEMENT_DELETE
311 inline void gc::operator delete( void*, void* ) {}
313 inline void gc::operator delete( void* p, GCPlacement gcp ) {
318 #ifdef GC_OPERATOR_NEW_ARRAY
320 inline void* gc::operator new[]( size_t size ) {
321 return gc::operator new( size );}
323 inline void* gc::operator new[]( size_t size, GCPlacement gcp ) {
324 return gc::operator new( size, gcp );}
326 inline void* gc::operator new[]( size_t size, void *p ) {
329 inline void gc::operator delete[]( void* obj ) {
330 gc::operator delete( obj );}
332 #ifdef GC_PLACEMENT_DELETE
333 inline void gc::operator delete[]( void*, void* ) {}
335 inline void gc::operator delete[]( void* p, GCPlacement gcp ) {
336 gc::operator delete(p); }
340 #endif /* GC_OPERATOR_NEW_ARRAY */
343 inline gc_cleanup::~gc_cleanup() {
344 GC_register_finalizer_ignore_self( GC_base(this), 0, 0, 0, 0 );}
346 inline void GC_CALLBACK gc_cleanup::cleanup( void* obj, void* displ ) {
347 ((gc_cleanup*) ((char*) obj + (ptrdiff_t) displ))->~gc_cleanup();}
349 inline gc_cleanup::gc_cleanup() {
350 GC_finalization_proc oldProc;
352 void* base = GC_base( (void *) this );
354 // Don't call the debug version, since this is a real base address.
355 GC_register_finalizer_ignore_self(
356 base, (GC_finalization_proc)cleanup, (void*) ((char*) this - (char*) base),
357 &oldProc, &oldData );
359 GC_register_finalizer_ignore_self( base, oldProc, oldData, 0, 0 );}}}
361 inline void* operator new(
364 GCCleanUpFunc cleanup,
370 obj = GC_MALLOC( size );
372 GC_REGISTER_FINALIZER_IGNORE_SELF(
373 obj, cleanup, clientData, 0, 0 );}
374 else if (gcp == PointerFreeGC) {
375 obj = GC_MALLOC_ATOMIC( size );}
377 obj = GC_MALLOC_UNCOLLECTABLE( size );};
380 # ifdef GC_PLACEMENT_DELETE
381 inline void operator delete (
384 GCCleanUpFunc cleanup,
391 #ifdef GC_OPERATOR_NEW_ARRAY
393 inline void* operator new[](
396 GCCleanUpFunc cleanup,
399 return ::operator new( size, gcp, cleanup, clientData );}
401 #endif /* GC_OPERATOR_NEW_ARRAY */
403 #endif /* GC_CPP_H */