boehm-gc/include/gc_cpp.h

   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 Both uncollectable and collectable objects can be explicitly deleted
  52 with "delete", which invokes an object's destructors and frees its
  53 storage immediately.
  54
  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:
  61
  62     A* a = ::new (GC, MyCleanup) A;
  63
  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.
  68
  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.
  76
  77 The collector cannot guarrantee that it will find all inaccessible
  78 objects.  In practice, it finds almost all of them.
  79
  80
  81 Cautions:
  82
  83 1. Be sure the collector has been augmented with "make c++".
  84
  85 2.  If your compiler supports the new "operator new[]" syntax, then
  86 add -DOPERATOR_NEW_ARRAY to the Makefile.
  87
  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:
  92
  93     class A: public gc {...};
  94     A* a1 = new A[ 10 ];        // collectable or uncollectable?
  95     A* a2 = new (GC) A[ 10 ];   // collectable
  96
  97 3. The destructors of collectable arrays of objects derived from
  98 "gc_cleanup" will not be invoked properly.  For example:
  99
 100     class A: public gc_cleanup {...};
 101     A* a = new (GC) A[ 10 ];    // destructors not invoked correctly
 102
 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
 106 clean-up function:
 107
 108     A* a = new (GC, MyCleanUp) A[ 10 ];
 109
 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.)
 113
 114 4. Compiler bugs:
 115
 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.
 120
 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.
 125
 126 5. GC name conflicts:
 127
 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.
 131
 132 ****************************************************************************/
 133
 134 #include "gc.h"
 135
 136 #ifndef THINK_CPLUS
 137 #define _cdecl
 138 #endif
 139
 140 #if ! defined( OPERATOR_NEW_ARRAY ) \
 141     && (__BORLANDC__ >= 0x450 || (__GNUC__ >= 2 && __GNUC_MINOR__ >= 6) \
 142         || __WATCOMC__ >= 1050)
 143 #   define OPERATOR_NEW_ARRAY
 144 #endif
 145
 146 enum GCPlacement {UseGC,
 147 #ifndef GC_NAME_CONFLICT
 148                   GC=UseGC,
 149 #endif
 150                   NoGC, PointerFreeGC};
 151
 152 class gc {public:
 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 );
 156
 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 */
 162     };
 163     /*
 164     Instances of classes derived from "gc" will be allocated in the
 165     collected heap by default, unless an explicit NoGC placement is
 166     specified. */
 167
 168 class gc_cleanup: virtual public gc {public:
 169     inline gc_cleanup();
 170     inline virtual ~gc_cleanup();
 171 private:
 172     inline static void _cdecl cleanup( void* obj, void* clientData );};
 173     /*
 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
 178     invoked. */
 179
 180 extern "C" {typedef void (*GCCleanUpFunc)( void* obj, void* clientData );}
 181
 182 inline void* operator new(
 183     size_t size,
 184     GCPlacement gcp,
 185     GCCleanUpFunc cleanup = 0,
 186     void* clientData = 0 );
 187     /*
 188     Allocates a collectable or uncollected object, according to the
 189     value of "gcp".
 190
 191     For collectable objects, if "cleanup" is non-null, then when the
 192     allocated object "obj" becomes inaccessible, the collector will
 193     invoke the function "cleanup( obj, clientData )" but will not
 194     invoke the object's destructors.  It is an error to explicitly
 195     delete an object allocated with a non-null "cleanup".
 196
 197     It is an error to specify a non-null "cleanup" with NoGC or for
 198     classes derived from "gc_cleanup" or containing members derived
 199     from "gc_cleanup". */
 200
 201 #ifdef OPERATOR_NEW_ARRAY
 202
 203 inline void* operator new[](
 204     size_t size,
 205     GCPlacement gcp,
 206     GCCleanUpFunc cleanup = 0,
 207     void* clientData = 0 );
 208     /*
 209     The operator new for arrays, identical to the above. */
 210
 211 #endif /* OPERATOR_NEW_ARRAY */
 212
 213 /****************************************************************************
 214
 215 Inline implementation
 216
 217 ****************************************************************************/
 218
 219 inline void* gc::operator new( size_t size ) {
 220     return GC_MALLOC( size );}
 221
 222 inline void* gc::operator new( size_t size, GCPlacement gcp ) {
 223     if (gcp == UseGC)
 224         return GC_MALLOC( size );
 225     else if (gcp == PointerFreeGC)
 226         return GC_MALLOC_ATOMIC( size );
 227     else
 228         return GC_MALLOC_UNCOLLECTABLE( size );}
 229
 230 inline void gc::operator delete( void* obj ) {
 231     GC_FREE( obj );}
 232
 233
 234 #ifdef OPERATOR_NEW_ARRAY
 235
 236 inline void* gc::operator new[]( size_t size ) {
 237     return gc::operator new( size );}
 238
 239 inline void* gc::operator new[]( size_t size, GCPlacement gcp ) {
 240     return gc::operator new( size, gcp );}
 241
 242 inline void gc::operator delete[]( void* obj ) {
 243     gc::operator delete( obj );}
 244
 245 #endif /* OPERATOR_NEW_ARRAY */
 246
 247
 248 inline gc_cleanup::~gc_cleanup() {
 249     GC_REGISTER_FINALIZER_IGNORE_SELF( GC_base(this), 0, 0, 0, 0 );}
 250
 251 inline void gc_cleanup::cleanup( void* obj, void* displ ) {
 252     ((gc_cleanup*) ((char*) obj + (ptrdiff_t) displ))->~gc_cleanup();}
 253
 254 inline gc_cleanup::gc_cleanup() {
 255     GC_finalization_proc oldProc;
 256     void* oldData;
 257     void* base = GC_base( (void *) this );
 258     if (0 != base)  {
 259       GC_REGISTER_FINALIZER_IGNORE_SELF(
 260         base, (GC_finalization_proc)cleanup, (void*) ((char*) this - (char*) base),
 261         &oldProc, &oldData );
 262       if (0 != oldProc) {
 263         GC_REGISTER_FINALIZER_IGNORE_SELF( base, oldProc, oldData, 0, 0 );}}}
 264
 265 inline void* operator new(
 266     size_t size,
 267     GCPlacement gcp,
 268     GCCleanUpFunc cleanup,
 269     void* clientData )
 270 {
 271     void* obj;
 272
 273     if (gcp == UseGC) {
 274         obj = GC_MALLOC( size );
 275         if (cleanup != 0)
 276             GC_REGISTER_FINALIZER_IGNORE_SELF(
 277                 obj, cleanup, clientData, 0, 0 );}
 278     else if (gcp == PointerFreeGC) {
 279         obj = GC_MALLOC_ATOMIC( size );}
 280     else {
 281         obj = GC_MALLOC_UNCOLLECTABLE( size );};
 282     return obj;}
 283
 284
 285 #ifdef OPERATOR_NEW_ARRAY
 286
 287 inline void* operator new[](
 288     size_t size,
 289     GCPlacement gcp,
 290     GCCleanUpFunc cleanup,
 291     void* clientData )
 292 {
 293     return ::operator new( size, gcp, cleanup, clientData );}
 294
 295 #endif /* OPERATOR_NEW_ARRAY */
 296
 297
 298 #endif /* GC_CPP_H */
 299