diff options
| author | Dave Love | 2003-06-05 18:00:24 +0000 |
|---|---|---|
| committer | Dave Love | 2003-06-05 18:00:24 +0000 |
| commit | d0982fbddb5d9202766a24ace3313b281a0a2eff (patch) | |
| tree | e1b13c9ff11ae2359d1b1dd0ca33a9b9be197fd8 /gc/include/weakpointer.h | |
| parent | 460ff54e9d7a1aca9043ac267025e17b7b299595 (diff) | |
| download | emacs-d0982fbddb5d9202766a24ace3313b281a0a2eff.tar.gz emacs-d0982fbddb5d9202766a24ace3313b281a0a2eff.zip | |
Not committed to branch, sorry.
Diffstat (limited to 'gc/include/weakpointer.h')
| -rw-r--r-- | gc/include/weakpointer.h | 221 |
1 files changed, 0 insertions, 221 deletions
diff --git a/gc/include/weakpointer.h b/gc/include/weakpointer.h deleted file mode 100644 index 84906b00a68..00000000000 --- a/gc/include/weakpointer.h +++ /dev/null | |||
| @@ -1,221 +0,0 @@ | |||
| 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 | |||