3 /****************************************************************************
4 Copyright (c) 1994 by Xerox Corporation. All rights reserved.
6 THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
7 OR IMPLIED. ANY USE IS AT YOUR OWN RISK.
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 ****************************************************************************
16 C++ Interface to the Boehm Collector
18 John R. Ellis and Jesse Hull
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).
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
32 Objects allocated with the built-in "::operator new" are uncollectable.
34 Objects derived from class "gc" are collectable. For example:
36 class A: public gc {...};
37 A* a = new A; // a is collectable.
39 Collectable instances of non-class types can be allocated using the GC
45 Uncollectable instances of classes derived from "gc" can be allocated
46 using the NoGC placement:
48 class A: public gc {...};
49 A* a = new (NoGC) A; // a is uncollectable.
51 Both uncollectable and collectable objects can be explicitly deleted
52 with "delete", which invokes an object's destructors and frees its
55 A collectable object may have a clean-up function, which will be
56 invoked when the collector discovers the object to be inaccessible.
57 An object derived from "gc_cleanup" or containing a member derived
58 from "gc_cleanup" has a default clean-up function that invokes the
59 object's destructors. Explicit clean-up functions may be specified as
60 an additional placement argument:
62 A* a = ::new (GC, MyCleanup) A;
64 An object is considered "accessible" by the collector if it can be
65 reached by a path of pointers from static variables, automatic
66 variables of active functions, or from some object with clean-up
67 enabled; pointers from an object to itself are ignored.
69 Thus, if objects A and B both have clean-up functions, and A points at
70 B, B is considered accessible. After A's clean-up is invoked and its
71 storage released, B will then become inaccessible and will have its
72 clean-up invoked. If A points at B and B points to A, forming a
73 cycle, then that's considered a storage leak, and neither will be
74 collectable. See the interface gc.h for low-level facilities for
75 handling such cycles of objects with clean-up.
77 The collector cannot guarrantee that it will find all inaccessible
78 objects. In practice, it finds almost all of them.
83 1. Be sure the collector has been augmented with "make c++".
85 2. If your compiler supports the new "operator new[]" syntax, then
86 add -DOPERATOR_NEW_ARRAY to the Makefile.
88 If your compiler doesn't support "operator new[]", beware that an
89 array of type T, where T is derived from "gc", may or may not be
90 allocated as a collectable object (it depends on the compiler). Use
91 the explicit GC placement to make the array collectable. For example:
93 class A: public gc {...};
94 A* a1 = new A[ 10 ]; // collectable or uncollectable?
95 A* a2 = new (GC) A[ 10 ]; // collectable
97 3. The destructors of collectable arrays of objects derived from
98 "gc_cleanup" will not be invoked properly. For example:
100 class A: public gc_cleanup {...};
101 A* a = new (GC) A[ 10 ]; // destructors not invoked correctly
103 Typically, only the destructor for the first element of the array will
104 be invoked when the array is garbage-collected. To get all the
105 destructors of any array executed, you must supply an explicit
108 A* a = new (GC, MyCleanUp) A[ 10 ];
110 (Implementing clean-up of arrays correctly, portably, and in a way
111 that preserves the correct exception semantics requires a language
112 extension, e.g. the "gc" keyword.)
116 * Solaris 2's CC (SC3.0) doesn't implement t->~T() correctly, so the
117 destructors of classes derived from gc_cleanup won't be invoked.
118 You'll have to explicitly register a clean-up function with
119 new-placement syntax.
121 * Evidently cfront 3.0 does not allow destructors to be explicitly
122 invoked using the ANSI-conforming syntax t->~T(). If you're using
123 cfront 3.0, you'll have to comment out the class gc_cleanup, which
124 uses explicit invocation.
126 5. GC name conflicts:
128 Many other systems seem to use the identifier "GC" as an abbreviation
129 for "Graphics Context". Since version 5.0, GC placement has been replaced
130 by UseGC. GC is an alias for UseGC, unless GC_NAME_CONFLICT is defined.
132 ****************************************************************************/
140 #if ! defined( OPERATOR_NEW_ARRAY ) \
141 && (__BORLANDC__ >= 0x450 || (__GNUC__ >= 2 && __GNUC_MINOR__ >= 6) \
142 || __WATCOMC__ >= 1050 || _MSC_VER >= 1100)
143 # define OPERATOR_NEW_ARRAY
146 enum GCPlacement {UseGC,
147 #ifndef GC_NAME_CONFLICT
150 NoGC, PointerFreeGC};
153 inline void* operator new( size_t size );
154 inline void* operator new( size_t size, GCPlacement gcp );
155 inline void operator delete( void* obj );
157 #ifdef OPERATOR_NEW_ARRAY
158 inline void* operator new[]( size_t size );
159 inline void* operator new[]( size_t size, GCPlacement gcp );
160 inline void operator delete[]( void* obj );
161 #endif /* OPERATOR_NEW_ARRAY */
164 Instances of classes derived from "gc" will be allocated in the
165 collected heap by default, unless an explicit NoGC placement is
168 class gc_cleanup: virtual public gc {public:
170 inline virtual ~gc_cleanup();
172 inline static void _cdecl cleanup( void* obj, void* clientData );};
174 Instances of classes derived from "gc_cleanup" will be allocated
175 in the collected heap by default. When the collector discovers an
176 inaccessible object derived from "gc_cleanup" or containing a
177 member derived from "gc_cleanup", its destructors will be
180 extern "C" {typedef void (*GCCleanUpFunc)( void* obj, void* clientData );}
183 // Disable warning that "no matching operator delete found; memory will
184 // not be freed if initialization throws an exception"
185 # pragma warning(disable:4291)
188 inline void* operator new(
191 GCCleanUpFunc cleanup = 0,
192 void* clientData = 0 );
194 Allocates a collectable or uncollected object, according to the
197 For collectable objects, if "cleanup" is non-null, then when the
198 allocated object "obj" becomes inaccessible, the collector will
199 invoke the function "cleanup( obj, clientData )" but will not
200 invoke the object's destructors. It is an error to explicitly
201 delete an object allocated with a non-null "cleanup".
203 It is an error to specify a non-null "cleanup" with NoGC or for
204 classes derived from "gc_cleanup" or containing members derived
205 from "gc_cleanup". */
207 #ifdef OPERATOR_NEW_ARRAY
210 /** This ensures that the system default operator new[] doesn't get
211 * undefined, which is what seems to happen on VC++ 6 for some reason
212 * if we define a multi-argument operator new[].
213 * There seems to be really redirect new in this environment without
214 * including this everywhere.
216 inline void *operator new[]( size_t size )
218 return GC_MALLOC_UNCOLLECTABLE( size );
221 inline void operator delete[](void* obj)
226 inline void* operator new( size_t size)
228 return GC_MALLOC_UNCOLLECTABLE( size);
231 inline void operator delete(void* obj)
237 // This new operator is used by VC++ in case of Debug builds !
238 inline void* operator new( size_t size,
240 const char * szFileName,
244 return GC_malloc_uncollectable( size );
246 return GC_debug_malloc_uncollectable(size, szFileName, nLine);
250 #endif /* _MSC_VER */
252 inline void* operator new[](
255 GCCleanUpFunc cleanup = 0,
256 void* clientData = 0 );
258 The operator new for arrays, identical to the above. */
260 #endif /* OPERATOR_NEW_ARRAY */
262 /****************************************************************************
264 Inline implementation
266 ****************************************************************************/
268 inline void* gc::operator new( size_t size ) {
269 return GC_MALLOC( size );}
271 inline void* gc::operator new( size_t size, GCPlacement gcp ) {
273 return GC_MALLOC( size );
274 else if (gcp == PointerFreeGC)
275 return GC_MALLOC_ATOMIC( size );
277 return GC_MALLOC_UNCOLLECTABLE( size );}
279 inline void gc::operator delete( void* obj ) {
283 #ifdef OPERATOR_NEW_ARRAY
285 inline void* gc::operator new[]( size_t size ) {
286 return gc::operator new( size );}
288 inline void* gc::operator new[]( size_t size, GCPlacement gcp ) {
289 return gc::operator new( size, gcp );}
291 inline void gc::operator delete[]( void* obj ) {
292 gc::operator delete( obj );}
294 #endif /* OPERATOR_NEW_ARRAY */
297 inline gc_cleanup::~gc_cleanup() {
298 GC_REGISTER_FINALIZER_IGNORE_SELF( GC_base(this), 0, 0, 0, 0 );}
300 inline void gc_cleanup::cleanup( void* obj, void* displ ) {
301 ((gc_cleanup*) ((char*) obj + (ptrdiff_t) displ))->~gc_cleanup();}
303 inline gc_cleanup::gc_cleanup() {
304 GC_finalization_proc oldProc;
306 void* base = GC_base( (void *) this );
308 GC_REGISTER_FINALIZER_IGNORE_SELF(
309 base, (GC_finalization_proc)cleanup, (void*) ((char*) this - (char*) base),
310 &oldProc, &oldData );
312 GC_REGISTER_FINALIZER_IGNORE_SELF( base, oldProc, oldData, 0, 0 );}}}
314 inline void* operator new(
317 GCCleanUpFunc cleanup,
323 obj = GC_MALLOC( size );
325 GC_REGISTER_FINALIZER_IGNORE_SELF(
326 obj, cleanup, clientData, 0, 0 );}
327 else if (gcp == PointerFreeGC) {
328 obj = GC_MALLOC_ATOMIC( size );}
330 obj = GC_MALLOC_UNCOLLECTABLE( size );};
334 #ifdef OPERATOR_NEW_ARRAY
336 inline void* operator new[](
339 GCCleanUpFunc cleanup,
342 return ::operator new( size, gcp, cleanup, clientData );}
344 #endif /* OPERATOR_NEW_ARRAY */
347 #endif /* GC_CPP_H */