src/mm/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 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 GC_CALLBACK
 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 ) && ! defined( __WATCOMC__ ) \
 164     && (!defined(_MSC_VER) || _MSC_VER > 1020)
 165 #  define GC_PLACEMENT_DELETE
 166 #endif
 167
 168 enum GCPlacement {UseGC,
 169 #ifndef GC_NAME_CONFLICT
 170                   GC=UseGC,
 171 #endif
 172                   NoGC, PointerFreeGC};
 173
 174 class gc {public:
 175     inline void* operator new( size_t size );
 176     inline void* operator new( size_t size, GCPlacement gcp );
 177     inline void* operator new( size_t size, void *p );
 178         /* Must be redefined here, since the other overloadings */
 179         /* hide the global definition.                          */
 180     inline void operator delete( void* obj );
 181 #   ifdef GC_PLACEMENT_DELETE
 182       inline void operator delete( void*, GCPlacement );
 183         /* called if construction fails.        */
 184       inline void operator delete( void*, void* );
 185 #   endif
 186
 187 #ifdef GC_OPERATOR_NEW_ARRAY
 188     inline void* operator new[]( size_t size );
 189     inline void* operator new[]( size_t size, GCPlacement gcp );
 190     inline void* operator new[]( size_t size, void *p );
 191     inline void operator delete[]( void* obj );
 192 #   ifdef GC_PLACEMENT_DELETE
 193       inline void operator delete[]( void*, GCPlacement );
 194       inline void operator delete[]( void*, void* );
 195 #   endif
 196 #endif /* GC_OPERATOR_NEW_ARRAY */
 197     };
 198     /*
 199     Instances of classes derived from "gc" will be allocated in the
 200     collected heap by default, unless an explicit NoGC placement is
 201     specified. */
 202
 203 class gc_cleanup: virtual public gc {public:
 204     inline gc_cleanup();
 205     inline virtual ~gc_cleanup();
 206 private:
 207     inline static void GC_cdecl cleanup( void* obj, void* clientData );};
 208     /*
 209     Instances of classes derived from "gc_cleanup" will be allocated
 210     in the collected heap by default.  When the collector discovers an
 211     inaccessible object derived from "gc_cleanup" or containing a
 212     member derived from "gc_cleanup", its destructors will be
 213     invoked. */
 214
 215 extern "C" {
 216     typedef void (GC_CALLBACK * GCCleanUpFunc)( void* obj, void* clientData );
 217 }
 218
 219 #ifdef _MSC_VER
 220   // Disable warning that "no matching operator delete found; memory will
 221   // not be freed if initialization throws an exception"
 222 # pragma warning(disable:4291)
 223 #endif
 224
 225 inline void* operator new(
 226     size_t size,
 227     GCPlacement gcp,
 228     GCCleanUpFunc cleanup = 0,
 229     void* clientData = 0 );
 230     /*
 231     Allocates a collectable or uncollected object, according to the
 232     value of "gcp".
 233
 234     For collectable objects, if "cleanup" is non-null, then when the
 235     allocated object "obj" becomes inaccessible, the collector will
 236     invoke the function "cleanup( obj, clientData )" but will not
 237     invoke the object's destructors.  It is an error to explicitly
 238     delete an object allocated with a non-null "cleanup".
 239
 240     It is an error to specify a non-null "cleanup" with NoGC or for
 241     classes derived from "gc_cleanup" or containing members derived
 242     from "gc_cleanup". */
 243
 244 #   ifdef GC_PLACEMENT_DELETE
 245       inline void operator delete( void*, GCPlacement, GCCleanUpFunc, void * );
 246 #   endif
 247
 248 #ifdef _MSC_VER
 249  /** This ensures that the system default operator new[] doesn't get
 250   *  undefined, which is what seems to happen on VC++ 6 for some reason
 251   *  if we define a multi-argument operator new[].
 252   *  There seems to be no way to redirect new in this environment without
 253   *  including this everywhere.
 254   */
 255 #if _MSC_VER > 1020
 256  void *operator new[]( size_t size );
 257
 258  void operator delete[](void* obj);
 259 #endif
 260
 261  void* operator new( size_t size);
 262
 263  void operator delete(void* obj);
 264
 265  // This new operator is used by VC++ in case of Debug builds !
 266  void* operator new(  size_t size,
 267                       int ,//nBlockUse,
 268                       const char * szFileName,
 269                       int nLine );
 270 #endif /* _MSC_VER */
 271
 272
 273 #ifdef GC_OPERATOR_NEW_ARRAY
 274
 275 inline void* operator new[](
 276     size_t size,
 277     GCPlacement gcp,
 278     GCCleanUpFunc cleanup = 0,
 279     void* clientData = 0 );
 280     /*
 281     The operator new for arrays, identical to the above. */
 282
 283 #endif /* GC_OPERATOR_NEW_ARRAY */
 284
 285 /****************************************************************************
 286
 287 Inline implementation
 288
 289 ****************************************************************************/
 290
 291 inline void* gc::operator new( size_t size ) {
 292     return GC_MALLOC( size );}
 293
 294 inline void* gc::operator new( size_t size, GCPlacement gcp ) {
 295     if (gcp == UseGC)
 296         return GC_MALLOC( size );
 297     else if (gcp == PointerFreeGC)
 298         return GC_MALLOC_ATOMIC( size );
 299     else
 300         return GC_MALLOC_UNCOLLECTABLE( size );}
 301
 302 inline void* gc::operator new( size_t size, void *p ) {
 303     return p;}
 304
 305 inline void gc::operator delete( void* obj ) {
 306     GC_FREE( obj );}
 307
 308 #ifdef GC_PLACEMENT_DELETE
 309   inline void gc::operator delete( void*, void* ) {}
 310
 311   inline void gc::operator delete( void* p, GCPlacement gcp ) {
 312     GC_FREE(p);
 313   }
 314 #endif
 315
 316 #ifdef GC_OPERATOR_NEW_ARRAY
 317
 318 inline void* gc::operator new[]( size_t size ) {
 319     return gc::operator new( size );}
 320
 321 inline void* gc::operator new[]( size_t size, GCPlacement gcp ) {
 322     return gc::operator new( size, gcp );}
 323
 324 inline void* gc::operator new[]( size_t size, void *p ) {
 325     return p;}
 326
 327 inline void gc::operator delete[]( void* obj ) {
 328     gc::operator delete( obj );}
 329
 330 #ifdef GC_PLACEMENT_DELETE
 331   inline void gc::operator delete[]( void*, void* ) {}
 332
 333   inline void gc::operator delete[]( void* p, GCPlacement gcp ) {
 334     gc::operator delete(p); }
 335
 336 #endif
 337
 338 #endif /* GC_OPERATOR_NEW_ARRAY */
 339
 340
 341 inline gc_cleanup::~gc_cleanup() {
 342     GC_register_finalizer_ignore_self( GC_base(this), 0, 0, 0, 0 );}
 343
 344 inline void GC_CALLBACK gc_cleanup::cleanup( void* obj, void* displ ) {
 345     ((gc_cleanup*) ((char*) obj + (ptrdiff_t) displ))->~gc_cleanup();}
 346
 347 inline gc_cleanup::gc_cleanup() {
 348     GC_finalization_proc oldProc;
 349     void* oldData;
 350     void* base = GC_base( (void *) this );
 351     if (0 != base)  {
 352       // Don't call the debug version, since this is a real base address.
 353       GC_register_finalizer_ignore_self(
 354         base, (GC_finalization_proc)cleanup, (void*) ((char*) this - (char*) base),
 355         &oldProc, &oldData );
 356       if (0 != oldProc) {
 357         GC_register_finalizer_ignore_self( base, oldProc, oldData, 0, 0 );}}}
 358
 359 inline void* operator new(
 360     size_t size,
 361     GCPlacement gcp,
 362     GCCleanUpFunc cleanup,
 363     void* clientData )
 364 {
 365     void* obj;
 366
 367     if (gcp == UseGC) {
 368         obj = GC_MALLOC( size );
 369         if (cleanup != 0)
 370             GC_REGISTER_FINALIZER_IGNORE_SELF(
 371                 obj, cleanup, clientData, 0, 0 );}
 372     else if (gcp == PointerFreeGC) {
 373         obj = GC_MALLOC_ATOMIC( size );}
 374     else {
 375         obj = GC_MALLOC_UNCOLLECTABLE( size );};
 376     return obj;}
 377
 378 # ifdef GC_PLACEMENT_DELETE
 379 inline void operator delete (
 380     void *p,
 381     GCPlacement gcp,
 382     GCCleanUpFunc cleanup,
 383     void* clientData )
 384 {
 385     GC_FREE(p);
 386 }
 387 # endif
 388
 389 #ifdef GC_OPERATOR_NEW_ARRAY
 390
 391 inline void* operator new[](
 392     size_t size,
 393     GCPlacement gcp,
 394     GCCleanUpFunc cleanup,
 395     void* clientData )
 396 {
 397     return ::operator new( size, gcp, cleanup, clientData );}
 398
 399 #endif /* GC_OPERATOR_NEW_ARRAY */
 400
 401
 402 #endif /* GC_CPP_H */
 403