Annotation of OpenXM_contrib/gc/weakpointer.h, Revision 1.1
1.1 ! maekawa 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:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to weakpointer.h CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM_contrib / gc