|
1 """ |
|
2 "Safe weakrefs", originally from pyDispatcher. |
|
3 |
|
4 Provides a way to safely weakref any function, including bound methods (which |
|
5 aren't handled by the core weakref module). |
|
6 """ |
|
7 |
|
8 import weakref, traceback |
|
9 |
|
10 def safeRef(target, onDelete = None): |
|
11 """Return a *safe* weak reference to a callable target |
|
12 |
|
13 target -- the object to be weakly referenced, if it's a |
|
14 bound method reference, will create a BoundMethodWeakref, |
|
15 otherwise creates a simple weakref. |
|
16 onDelete -- if provided, will have a hard reference stored |
|
17 to the callable to be called after the safe reference |
|
18 goes out of scope with the reference object, (either a |
|
19 weakref or a BoundMethodWeakref) as argument. |
|
20 """ |
|
21 if hasattr(target, 'im_self'): |
|
22 if target.im_self is not None: |
|
23 # Turn a bound method into a BoundMethodWeakref instance. |
|
24 # Keep track of these instances for lookup by disconnect(). |
|
25 assert hasattr(target, 'im_func'), """safeRef target %r has im_self, but no im_func, don't know how to create reference"""%( target,) |
|
26 reference = get_bound_method_weakref( |
|
27 target=target, |
|
28 onDelete=onDelete |
|
29 ) |
|
30 return reference |
|
31 if callable(onDelete): |
|
32 return weakref.ref(target, onDelete) |
|
33 else: |
|
34 return weakref.ref( target ) |
|
35 |
|
36 class BoundMethodWeakref(object): |
|
37 """'Safe' and reusable weak references to instance methods |
|
38 |
|
39 BoundMethodWeakref objects provide a mechanism for |
|
40 referencing a bound method without requiring that the |
|
41 method object itself (which is normally a transient |
|
42 object) is kept alive. Instead, the BoundMethodWeakref |
|
43 object keeps weak references to both the object and the |
|
44 function which together define the instance method. |
|
45 |
|
46 Attributes: |
|
47 key -- the identity key for the reference, calculated |
|
48 by the class's calculateKey method applied to the |
|
49 target instance method |
|
50 deletionMethods -- sequence of callable objects taking |
|
51 single argument, a reference to this object which |
|
52 will be called when *either* the target object or |
|
53 target function is garbage collected (i.e. when |
|
54 this object becomes invalid). These are specified |
|
55 as the onDelete parameters of safeRef calls. |
|
56 weakSelf -- weak reference to the target object |
|
57 weakFunc -- weak reference to the target function |
|
58 |
|
59 Class Attributes: |
|
60 _allInstances -- class attribute pointing to all live |
|
61 BoundMethodWeakref objects indexed by the class's |
|
62 calculateKey(target) method applied to the target |
|
63 objects. This weak value dictionary is used to |
|
64 short-circuit creation so that multiple references |
|
65 to the same (object, function) pair produce the |
|
66 same BoundMethodWeakref instance. |
|
67 |
|
68 """ |
|
69 |
|
70 _allInstances = weakref.WeakValueDictionary() |
|
71 |
|
72 def __new__( cls, target, onDelete=None, *arguments,**named ): |
|
73 """Create new instance or return current instance |
|
74 |
|
75 Basically this method of construction allows us to |
|
76 short-circuit creation of references to already- |
|
77 referenced instance methods. The key corresponding |
|
78 to the target is calculated, and if there is already |
|
79 an existing reference, that is returned, with its |
|
80 deletionMethods attribute updated. Otherwise the |
|
81 new instance is created and registered in the table |
|
82 of already-referenced methods. |
|
83 """ |
|
84 key = cls.calculateKey(target) |
|
85 current =cls._allInstances.get(key) |
|
86 if current is not None: |
|
87 current.deletionMethods.append( onDelete) |
|
88 return current |
|
89 else: |
|
90 base = super( BoundMethodWeakref, cls).__new__( cls ) |
|
91 cls._allInstances[key] = base |
|
92 base.__init__( target, onDelete, *arguments,**named) |
|
93 return base |
|
94 |
|
95 def __init__(self, target, onDelete=None): |
|
96 """Return a weak-reference-like instance for a bound method |
|
97 |
|
98 target -- the instance-method target for the weak |
|
99 reference, must have im_self and im_func attributes |
|
100 and be reconstructable via: |
|
101 target.im_func.__get__( target.im_self ) |
|
102 which is true of built-in instance methods. |
|
103 onDelete -- optional callback which will be called |
|
104 when this weak reference ceases to be valid |
|
105 (i.e. either the object or the function is garbage |
|
106 collected). Should take a single argument, |
|
107 which will be passed a pointer to this object. |
|
108 """ |
|
109 def remove(weak, self=self): |
|
110 """Set self.isDead to true when method or instance is destroyed""" |
|
111 methods = self.deletionMethods[:] |
|
112 del self.deletionMethods[:] |
|
113 try: |
|
114 del self.__class__._allInstances[ self.key ] |
|
115 except KeyError: |
|
116 pass |
|
117 for function in methods: |
|
118 try: |
|
119 if callable( function ): |
|
120 function( self ) |
|
121 except Exception, e: |
|
122 try: |
|
123 traceback.print_exc() |
|
124 except AttributeError, err: |
|
125 print '''Exception during saferef %s cleanup function %s: %s'''%( |
|
126 self, function, e |
|
127 ) |
|
128 self.deletionMethods = [onDelete] |
|
129 self.key = self.calculateKey( target ) |
|
130 self.weakSelf = weakref.ref(target.im_self, remove) |
|
131 self.weakFunc = weakref.ref(target.im_func, remove) |
|
132 self.selfName = str(target.im_self) |
|
133 self.funcName = str(target.im_func.__name__) |
|
134 |
|
135 def calculateKey( cls, target ): |
|
136 """Calculate the reference key for this reference |
|
137 |
|
138 Currently this is a two-tuple of the id()'s of the |
|
139 target object and the target function respectively. |
|
140 """ |
|
141 return (id(target.im_self),id(target.im_func)) |
|
142 calculateKey = classmethod( calculateKey ) |
|
143 |
|
144 def __str__(self): |
|
145 """Give a friendly representation of the object""" |
|
146 return """%s( %s.%s )"""%( |
|
147 self.__class__.__name__, |
|
148 self.selfName, |
|
149 self.funcName, |
|
150 ) |
|
151 |
|
152 __repr__ = __str__ |
|
153 |
|
154 def __nonzero__( self ): |
|
155 """Whether we are still a valid reference""" |
|
156 return self() is not None |
|
157 |
|
158 def __cmp__( self, other ): |
|
159 """Compare with another reference""" |
|
160 if not isinstance (other,self.__class__): |
|
161 return cmp( self.__class__, type(other) ) |
|
162 return cmp( self.key, other.key) |
|
163 |
|
164 def __call__(self): |
|
165 """Return a strong reference to the bound method |
|
166 |
|
167 If the target cannot be retrieved, then will |
|
168 return None, otherwise returns a bound instance |
|
169 method for our object and function. |
|
170 |
|
171 Note: |
|
172 You may call this method any number of times, |
|
173 as it does not invalidate the reference. |
|
174 """ |
|
175 target = self.weakSelf() |
|
176 if target is not None: |
|
177 function = self.weakFunc() |
|
178 if function is not None: |
|
179 return function.__get__(target) |
|
180 return None |
|
181 |
|
182 class BoundNonDescriptorMethodWeakref(BoundMethodWeakref): |
|
183 """A specialized BoundMethodWeakref, for platforms where instance methods |
|
184 are not descriptors. |
|
185 |
|
186 It assumes that the function name and the target attribute name are the |
|
187 same, instead of assuming that the function is a descriptor. This approach |
|
188 is equally fast, but not 100% reliable because functions can be stored on an |
|
189 attribute named differenty than the function's name such as in: |
|
190 |
|
191 class A: pass |
|
192 def foo(self): return "foo" |
|
193 A.bar = foo |
|
194 |
|
195 But this shouldn't be a common use case. So, on platforms where methods |
|
196 aren't descriptors (such as Jython) this implementation has the advantage |
|
197 of working in the most cases. |
|
198 """ |
|
199 def __init__(self, target, onDelete=None): |
|
200 """Return a weak-reference-like instance for a bound method |
|
201 |
|
202 target -- the instance-method target for the weak |
|
203 reference, must have im_self and im_func attributes |
|
204 and be reconstructable via: |
|
205 target.im_func.__get__( target.im_self ) |
|
206 which is true of built-in instance methods. |
|
207 onDelete -- optional callback which will be called |
|
208 when this weak reference ceases to be valid |
|
209 (i.e. either the object or the function is garbage |
|
210 collected). Should take a single argument, |
|
211 which will be passed a pointer to this object. |
|
212 """ |
|
213 assert getattr(target.im_self, target.__name__) == target, \ |
|
214 ("method %s isn't available as the attribute %s of %s" % |
|
215 (target, target.__name__, target.im_self)) |
|
216 super(BoundNonDescriptorMethodWeakref, self).__init__(target, onDelete) |
|
217 |
|
218 def __call__(self): |
|
219 """Return a strong reference to the bound method |
|
220 |
|
221 If the target cannot be retrieved, then will |
|
222 return None, otherwise returns a bound instance |
|
223 method for our object and function. |
|
224 |
|
225 Note: |
|
226 You may call this method any number of times, |
|
227 as it does not invalidate the reference. |
|
228 """ |
|
229 target = self.weakSelf() |
|
230 if target is not None: |
|
231 function = self.weakFunc() |
|
232 if function is not None: |
|
233 # Using curry() would be another option, but it erases the |
|
234 # "signature" of the function. That is, after a function is |
|
235 # curried, the inspect module can't be used to determine how |
|
236 # many arguments the function expects, nor what keyword |
|
237 # arguments it supports, and pydispatcher needs this |
|
238 # information. |
|
239 return getattr(target, function.__name__) |
|
240 return None |
|
241 |
|
242 def get_bound_method_weakref(target, onDelete): |
|
243 """Instantiates the appropiate BoundMethodWeakRef, depending on the details of |
|
244 the underlying class method implementation""" |
|
245 if hasattr(target, '__get__'): |
|
246 # target method is a descriptor, so the default implementation works: |
|
247 return BoundMethodWeakref(target=target, onDelete=onDelete) |
|
248 else: |
|
249 # no luck, use the alternative implementation: |
|
250 return BoundNonDescriptorMethodWeakref(target=target, onDelete=onDelete) |