boehm-gc/include/weakpointer.h

   1 #ifndef _weakpointer_h_
   2 #define _weakpointer_h_
   3
   4 /****************************************************************************
   5
   6 WeakPointer and CleanUp
   7
   8     Copyright (c) 1991 by Xerox Corporation.  All rights reserved.
   9
  10     THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
  11     OR IMPLIED.  ANY USE IS AT YOUR OWN RISK.
  12
  13     Permission is hereby granted to copy this code for any purpose,
  14     provided the above notices are retained on all copies.
  15
  16     Last modified on Mon Jul 17 18:16:01 PDT 1995 by ellis
  17
  18 ****************************************************************************/
  19
  20 /****************************************************************************
  21
  22 WeakPointer
  23
  24 A weak pointer is a pointer to a heap-allocated object that doesn't
  25 prevent the object from being garbage collected. Weak pointers can be
  26 used to track which objects haven't yet been reclaimed by the
  27 collector. A weak pointer is deactivated when the collector discovers
  28 its referent object is unreachable by normal pointers (reachability
  29 and deactivation are defined more precisely below). A deactivated weak
  30 pointer remains deactivated forever.
  31
  32 ****************************************************************************/
  33
  34
  35 template< class T > class WeakPointer {
  36 public:
  37
  38 WeakPointer( T* t = 0 )
  39     /* Constructs a weak pointer for *t. t may be null. It is an error
  40        if t is non-null and *t is not a collected object. */
  41     {impl = _WeakPointer_New( t );}
  42
  43 T* Pointer()
  44     /* wp.Pointer() returns a pointer to the referent object of wp or
  45        null if wp has been deactivated (because its referent object
  46        has been discovered unreachable by the collector). */
  47     {return (T*) _WeakPointer_Pointer( this->impl );}
  48
  49 int operator==( WeakPointer< T > wp2 )
  50     /* Given weak pointers wp1 and wp2, if wp1 == wp2, then wp1 and
  51        wp2 refer to the same object. If wp1 != wp2, then either wp1
  52        and wp2 don't refer to the same object, or if they do, one or
  53        both of them has been deactivated. (Note: If objects t1 and t2
  54        are never made reachable by their clean-up functions, then
  55        WeakPointer<T>(t1) == WeakPointer<T>(t2) if and only t1 == t2.) */
  56     {return _WeakPointer_Equal( this->impl, wp2.impl );}
  57
  58 int Hash()
  59     /* Returns a hash code suitable for use by multiplicative- and
  60        division-based hash tables. If wp1 == wp2, then wp1.Hash() ==
  61        wp2.Hash(). */
  62     {return _WeakPointer_Hash( this->impl );}
  63
  64 private:
  65 void* impl;
  66 };
  67
  68 /*****************************************************************************
  69
  70 CleanUp
  71
  72 A garbage-collected object can have an associated clean-up function
  73 that will be invoked some time after the collector discovers the
  74 object is unreachable via normal pointers. Clean-up functions can be
  75 used to release resources such as open-file handles or window handles
  76 when their containing objects become unreachable.  If a C++ object has
  77 a non-empty explicit destructor (i.e. it contains programmer-written
  78 code), the destructor will be automatically registered as the object's
  79 initial clean-up function.
  80
  81 There is no guarantee that the collector will detect every unreachable
  82 object (though it will find almost all of them). Clients should not
  83 rely on clean-up to cause some action to occur immediately -- clean-up
  84 is only a mechanism for improving resource usage.
  85
  86 Every object with a clean-up function also has a clean-up queue. When
  87 the collector finds the object is unreachable, it enqueues it on its
  88 queue. The clean-up function is applied when the object is removed
  89 from the queue. By default, objects are enqueued on the garbage
  90 collector's queue, and the collector removes all objects from its
  91 queue after each collection. If a client supplies another queue for
  92 objects, it is his responsibility to remove objects (and cause their
  93 functions to be called) by polling it periodically.
  94
  95 Clean-up queues allow clean-up functions accessing global data to
  96 synchronize with the main program. Garbage collection can occur at any
  97 time, and clean-ups invoked by the collector might access data in an
  98 inconsistent state. A client can control this by defining an explicit
  99 queue for objects and polling it at safe points.
 100
 101 The following definitions are used by the specification below:
 102
 103 Given a pointer t to a collected object, the base object BO(t) is the
 104 value returned by new when it created the object. (Because of multiple
 105 inheritance, t and BO(t) may not be the same address.)
 106
 107 A weak pointer wp references an object *t if BO(wp.Pointer()) ==
 108 BO(t).
 109
 110 ***************************************************************************/
 111
 112 template< class T, class Data > class CleanUp {
 113 public:
 114
 115 static void Set( T* t, void c( Data* d, T* t ), Data* d = 0 )
 116     /* Sets the clean-up function of object BO(t) to be <c, d>,
 117        replacing any previously defined clean-up function for BO(t); c
 118        and d can be null, but t cannot. Sets the clean-up queue for
 119        BO(t) to be the collector's queue. When t is removed from its
 120        clean-up queue, its clean-up will be applied by calling c(d,
 121        t). It is an error if *t is not a collected object. */
 122        {_CleanUp_Set( t, c, d );}
 123
 124 static void Call( T* t )
 125     /* Sets the new clean-up function for BO(t) to be null and, if the
 126        old one is non-null, calls it immediately, even if BO(t) is
 127        still reachable. Deactivates any weak pointers to BO(t). */
 128        {_CleanUp_Call( t );}
 129
 130 class Queue {public:
 131     Queue()
 132         /* Constructs a new queue. */
 133             {this->head = _CleanUp_Queue_NewHead();}
 134
 135     void Set( T* t )
 136         /* q.Set(t) sets the clean-up queue of BO(t) to be q. */
 137             {_CleanUp_Queue_Set( this->head, t );}
 138
 139     int Call()
 140         /* If q is non-empty, q.Call() removes the first object and
 141            calls its clean-up function; does nothing if q is
 142            empty. Returns true if there are more objects in the
 143            queue. */
 144            {return _CleanUp_Queue_Call( this->head );}
 145
 146     private:
 147     void* head;
 148     };
 149 };
 150
 151 /**********************************************************************
 152
 153 Reachability and Clean-up
 154
 155 An object O is reachable if it can be reached via a non-empty path of
 156 normal pointers from the registers, stacks, global variables, or an
 157 object with a non-null clean-up function (including O itself),
 158 ignoring pointers from an object to itself.
 159
 160 This definition of reachability ensures that if object B is accessible
 161 from object A (and not vice versa) and if both A and B have clean-up
 162 functions, then A will always be cleaned up before B. Note that as
 163 long as an object with a clean-up function is contained in a cycle of
 164 pointers, it will always be reachable and will never be cleaned up or
 165 collected.
 166
 167 When the collector finds an unreachable object with a null clean-up
 168 function, it atomically deactivates all weak pointers referencing the
 169 object and recycles its storage. If object B is accessible from object
 170 A via a path of normal pointers, A will be discovered unreachable no
 171 later than B, and a weak pointer to A will be deactivated no later
 172 than a weak pointer to B.
 173
 174 When the collector finds an unreachable object with a non-null
 175 clean-up function, the collector atomically deactivates all weak
 176 pointers referencing the object, redefines its clean-up function to be
 177 null, and enqueues it on its clean-up queue. The object then becomes
 178 reachable again and remains reachable at least until its clean-up
 179 function executes.
 180
 181 The clean-up function is assured that its argument is the only
 182 accessible pointer to the object. Nothing prevents the function from
 183 redefining the object's clean-up function or making the object
 184 reachable again (for example, by storing the pointer in a global
 185 variable).
 186
 187 If the clean-up function does not make its object reachable again and
 188 does not redefine its clean-up function, then the object will be
 189 collected by a subsequent collection (because the object remains
 190 unreachable and now has a null clean-up function). If the clean-up
 191 function does make its object reachable again and a clean-up function
 192 is subsequently redefined for the object, then the new clean-up
 193 function will be invoked the next time the collector finds the object
 194 unreachable.
 195
 196 Note that a destructor for a collected object cannot safely redefine a
 197 clean-up function for its object, since after the destructor executes,
 198 the object has been destroyed into "raw memory". (In most
 199 implementations, destroying an object mutates its vtbl.)
 200
 201 Finally, note that calling delete t on a collected object first
 202 deactivates any weak pointers to t and then invokes its clean-up
 203 function (destructor).
 204
 205 **********************************************************************/
 206
 207 extern "C" {
 208     void* _WeakPointer_New( void* t );
 209     void* _WeakPointer_Pointer( void* wp );
 210     int _WeakPointer_Equal( void* wp1, void* wp2 );
 211     int _WeakPointer_Hash( void* wp );
 212     void _CleanUp_Set( void* t, void (*c)( void* d, void* t ), void* d );
 213     void _CleanUp_Call( void* t );
 214     void* _CleanUp_Queue_NewHead ();
 215     void _CleanUp_Queue_Set( void* h, void* t );
 216     int _CleanUp_Queue_Call( void* h );
 217 }
 218
 219 #endif /* _weakpointer_h_ */
 220
 221