Annotation of OpenXM_contrib/gc/weakpointer.h, Revision 1.1.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