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 guarantee 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 -DGC_OPERATOR_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
****************************************************************************/
139
# define GC_cdecl _cdecl
142
#if ! defined( GC_NO_OPERATOR_NEW_ARRAY ) \
143
&& !defined(_ENABLE_ARRAYNEW) /* Digimars */ \
144
&& (defined(__BORLANDC__) && (__BORLANDC__ < 0x450) \
145
|| (defined(__GNUC__) && \
146
(__GNUC__ < 2 || __GNUC__ == 2 && __GNUC_MINOR__ < 6)) \
147
|| (defined(__WATCOMC__) && __WATCOMC__ < 1050))
148
# define GC_NO_OPERATOR_NEW_ARRAY
151
#if !defined(GC_NO_OPERATOR_NEW_ARRAY) && !defined(GC_OPERATOR_NEW_ARRAY)
152
# define GC_OPERATOR_NEW_ARRAY
155
#if ! defined ( __BORLANDC__ ) /* Confuses the Borland compiler. */ \
156
&& ! defined ( __sgi )
157
# define GC_PLACEMENT_DELETE
160
enum GCPlacement {UseGC,
161
#ifndef GC_NAME_CONFLICT
164
NoGC, PointerFreeGC};
167
inline void* operator new( size_t size );
168
inline void* operator new( size_t size, GCPlacement gcp );
169
inline void* operator new( size_t size, void *p );
170
/* Must be redefined here, since the other overloadings */
171
/* hide the global definition. */
172
inline void operator delete( void* obj );
173
# ifdef GC_PLACEMENT_DELETE
174
inline void operator delete( void*, void* );
177
#ifdef GC_OPERATOR_NEW_ARRAY
178
inline void* operator new[]( size_t size );
179
inline void* operator new[]( size_t size, GCPlacement gcp );
180
inline void* operator new[]( size_t size, void *p );
181
inline void operator delete[]( void* obj );
182
# ifdef GC_PLACEMENT_DELETE
183
inline void gc::operator delete[]( void*, void* );
185
#endif /* GC_OPERATOR_NEW_ARRAY */
188
Instances of classes derived from "gc" will be allocated in the
189
collected heap by default, unless an explicit NoGC placement is
192
class gc_cleanup: virtual public gc {public:
194
inline virtual ~gc_cleanup();
196
inline static void GC_cdecl cleanup( void* obj, void* clientData );};
198
Instances of classes derived from "gc_cleanup" will be allocated
199
in the collected heap by default. When the collector discovers an
200
inaccessible object derived from "gc_cleanup" or containing a
201
member derived from "gc_cleanup", its destructors will be
204
extern "C" {typedef void (*GCCleanUpFunc)( void* obj, void* clientData );}
207
// Disable warning that "no matching operator delete found; memory will
208
// not be freed if initialization throws an exception"
209
# pragma warning(disable:4291)
212
inline void* operator new(
215
GCCleanUpFunc cleanup = 0,
216
void* clientData = 0 );
218
Allocates a collectable or uncollected object, according to the
221
For collectable objects, if "cleanup" is non-null, then when the
222
allocated object "obj" becomes inaccessible, the collector will
223
invoke the function "cleanup( obj, clientData )" but will not
224
invoke the object's destructors. It is an error to explicitly
225
delete an object allocated with a non-null "cleanup".
227
It is an error to specify a non-null "cleanup" with NoGC or for
228
classes derived from "gc_cleanup" or containing members derived
229
from "gc_cleanup". */
233
/** This ensures that the system default operator new[] doesn't get
234
* undefined, which is what seems to happen on VC++ 6 for some reason
235
* if we define a multi-argument operator new[].
236
* There seems to be really redirect new in this environment without
237
* including this everywhere.
239
void *operator new[]( size_t size );
241
void operator delete[](void* obj);
243
void* operator new( size_t size);
245
void operator delete(void* obj);
247
// This new operator is used by VC++ in case of Debug builds !
248
void* operator new( size_t size,
250
const char * szFileName,
252
#endif /* _MSC_VER */
255
#ifdef GC_OPERATOR_NEW_ARRAY
257
inline void* operator new[](
260
GCCleanUpFunc cleanup = 0,
261
void* clientData = 0 );
263
The operator new for arrays, identical to the above. */
265
#endif /* GC_OPERATOR_NEW_ARRAY */
267
/****************************************************************************
269
Inline implementation
271
****************************************************************************/
273
inline void* gc::operator new( size_t size ) {
274
return GC_MALLOC( size );}
276
inline void* gc::operator new( size_t size, GCPlacement gcp ) {
278
return GC_MALLOC( size );
279
else if (gcp == PointerFreeGC)
280
return GC_MALLOC_ATOMIC( size );
282
return GC_MALLOC_UNCOLLECTABLE( size );}
284
inline void* gc::operator new( size_t size, void *p ) {
287
inline void gc::operator delete( void* obj ) {
290
#ifdef GC_PLACEMENT_DELETE
291
inline void gc::operator delete( void*, void* ) {}
294
#ifdef GC_OPERATOR_NEW_ARRAY
296
inline void* gc::operator new[]( size_t size ) {
297
return gc::operator new( size );}
299
inline void* gc::operator new[]( size_t size, GCPlacement gcp ) {
300
return gc::operator new( size, gcp );}
302
inline void* gc::operator new[]( size_t size, void *p ) {
305
inline void gc::operator delete[]( void* obj ) {
306
gc::operator delete( obj );}
308
#ifdef GC_PLACEMENT_DELETE
309
inline void gc::operator delete[]( void*, void* ) {}
312
#endif /* GC_OPERATOR_NEW_ARRAY */
315
inline gc_cleanup::~gc_cleanup() {
316
GC_register_finalizer_ignore_self( GC_base(this), 0, 0, 0, 0 );}
318
inline void gc_cleanup::cleanup( void* obj, void* displ ) {
319
((gc_cleanup*) ((char*) obj + (ptrdiff_t) displ))->~gc_cleanup();}
321
inline gc_cleanup::gc_cleanup() {
322
GC_finalization_proc oldProc;
324
void* base = GC_base( (void *) this );
326
// Don't call the debug version, since this is a real base address.
327
GC_register_finalizer_ignore_self(
328
base, (GC_finalization_proc)cleanup, (void*) ((char*) this - (char*) base),
329
&oldProc, &oldData );
331
GC_register_finalizer_ignore_self( base, oldProc, oldData, 0, 0 );}}}
333
inline void* operator new(
336
GCCleanUpFunc cleanup,
342
obj = GC_MALLOC( size );
344
GC_REGISTER_FINALIZER_IGNORE_SELF(
345
obj, cleanup, clientData, 0, 0 );}
346
else if (gcp == PointerFreeGC) {
347
obj = GC_MALLOC_ATOMIC( size );}
349
obj = GC_MALLOC_UNCOLLECTABLE( size );};
353
#ifdef GC_OPERATOR_NEW_ARRAY
355
inline void* operator new[](
358
GCCleanUpFunc cleanup,
361
return ::operator new( size, gcp, cleanup, clientData );}
363
#endif /* GC_OPERATOR_NEW_ARRAY */
366
#endif /* GC_CPP_H */
added
removed
src/gc/include/gc_cpp.h
