Fred Drake | ebcf6a8 | 2001-02-01 05:20:20 +0000 | [diff] [blame] | 1 | \section{\module{weakref} --- |
| 2 | Weak references} |
| 3 | |
| 4 | \declaremodule{extension}{weakref} |
Fred Drake | eedf985 | 2001-04-11 19:17:11 +0000 | [diff] [blame] | 5 | \modulesynopsis{Support for weak references and weak dictionaries.} |
Fred Drake | ebcf6a8 | 2001-02-01 05:20:20 +0000 | [diff] [blame] | 6 | \moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org} |
Martin v. Löwis | 5e16333 | 2001-02-27 18:36:56 +0000 | [diff] [blame] | 7 | \moduleauthor{Neil Schemenauer}{nas@arctrix.com} |
Fred Drake | 0c20904 | 2001-06-29 16:25:07 +0000 | [diff] [blame] | 8 | \moduleauthor{Martin von L\"owis}{martin@loewis.home.cs.tu-berlin.de} |
Fred Drake | ebcf6a8 | 2001-02-01 05:20:20 +0000 | [diff] [blame] | 9 | \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} |
| 10 | |
| 11 | \versionadded{2.1} |
| 12 | |
| 13 | |
| 14 | The \module{weakref} module allows the Python programmer to create |
| 15 | \dfn{weak references} to objects. |
| 16 | |
| 17 | XXX --- need to say more here! |
| 18 | |
| 19 | Not all objects can be weakly referenced; those objects which do |
Fred Drake | 5e0dfac | 2001-03-23 04:36:02 +0000 | [diff] [blame] | 20 | include class instances, functions written in Python (but not in C), |
| 21 | and methods (both bound and unbound). Extension types can easily |
Fred Drake | ebcf6a8 | 2001-02-01 05:20:20 +0000 | [diff] [blame] | 22 | be made to support weak references; see section \ref{weakref-extension}, |
| 23 | ``Weak References in Extension Types,'' for more information. |
| 24 | |
Fred Drake | ebcf6a8 | 2001-02-01 05:20:20 +0000 | [diff] [blame] | 25 | |
| 26 | \begin{funcdesc}{ref}{object\optional{, callback}} |
| 27 | Return a weak reference to \var{object}. If \var{callback} is |
| 28 | provided, it will be called when the object is about to be |
| 29 | finalized; the weak reference object will be passed as the only |
| 30 | parameter to the callback; the referent will no longer be available. |
| 31 | The original object can be retrieved by calling the reference |
| 32 | object, if the referent is still alive. |
| 33 | |
| 34 | It is allowable for many weak references to be constructed for the |
| 35 | same object. Callbacks registered for each weak reference will be |
| 36 | called from the most recently registered callback to the oldest |
| 37 | registered callback. |
| 38 | |
| 39 | Exceptions raised by the callback will be noted on the standard |
Andrew M. Kuchling | e7d7e6c | 2001-02-14 02:39:11 +0000 | [diff] [blame] | 40 | error output, but cannot be propagated; they are handled in exactly |
Fred Drake | ebcf6a8 | 2001-02-01 05:20:20 +0000 | [diff] [blame] | 41 | the same way as exceptions raised from an object's |
| 42 | \method{__del__()} method. |
Martin v. Löwis | 5e16333 | 2001-02-27 18:36:56 +0000 | [diff] [blame] | 43 | |
| 44 | Weak references are hashable if the \var{object} is hashable. They |
| 45 | will maintain their hash value even after the \var{object} was |
| 46 | deleted. If \function{hash()} is called the first time only after |
| 47 | the \var{object} was deleted, the call will raise |
| 48 | \exception{TypeError}. |
| 49 | |
Fred Drake | 3a2c462 | 2001-10-26 03:00:39 +0000 | [diff] [blame] | 50 | Weak references support tests for equality, but not ordering. If |
| 51 | the \var{object} is still alive, two references are equal if the |
| 52 | objects are equal (regardless of the \var{callback}). If |
| 53 | \var{object} has been deleted, they are equal only if the references |
| 54 | being compared are the same reference object. |
Fred Drake | ebcf6a8 | 2001-02-01 05:20:20 +0000 | [diff] [blame] | 55 | \end{funcdesc} |
| 56 | |
Fred Drake | ebcf6a8 | 2001-02-01 05:20:20 +0000 | [diff] [blame] | 57 | \begin{funcdesc}{proxy}{object\optional{, callback}} |
| 58 | Return a proxy to \var{object} which uses a weak reference. This |
| 59 | supports use of the proxy in most contexts instead of requiring the |
| 60 | explicit dereferencing used with weak reference objects. The |
| 61 | returned object will have a type of either \code{ProxyType} or |
| 62 | \code{CallableProxyType}, depending on whether \var{object} is |
| 63 | callable. Proxy objects are not hashable regardless of the |
| 64 | referent; this avoids a number of problems related to their |
| 65 | fundamentally mutable nature, and prevent their use as dictionary |
Fred Drake | e7ec1ef | 2001-05-10 17:22:17 +0000 | [diff] [blame] | 66 | keys. \var{callback} is the same as the parameter of the same name |
Fred Drake | ebcf6a8 | 2001-02-01 05:20:20 +0000 | [diff] [blame] | 67 | to the \function{ref()} function. |
| 68 | \end{funcdesc} |
| 69 | |
| 70 | \begin{funcdesc}{getweakrefcount}{object} |
| 71 | Return the number of weak references and proxies which refer to |
| 72 | \var{object}. |
| 73 | \end{funcdesc} |
| 74 | |
| 75 | \begin{funcdesc}{getweakrefs}{object} |
| 76 | Return a list of all weak reference and proxy objects which refer to |
| 77 | \var{object}. |
| 78 | \end{funcdesc} |
| 79 | |
Martin v. Löwis | 5e16333 | 2001-02-27 18:36:56 +0000 | [diff] [blame] | 80 | \begin{classdesc}{WeakKeyDictionary}{\optional{dict}} |
Fred Drake | ac154a1 | 2001-04-10 19:57:58 +0000 | [diff] [blame] | 81 | Mapping class that references keys weakly. Entries in the |
| 82 | dictionary will be discarded when there is no longer a strong |
| 83 | reference to the key. This can be used to associate additional data |
| 84 | with an object owned by other parts of an application without adding |
| 85 | attributes to those objects. This can be especially useful with |
| 86 | objects that override attribute accesses. |
Martin v. Löwis | 5e16333 | 2001-02-27 18:36:56 +0000 | [diff] [blame] | 87 | \end{classdesc} |
| 88 | |
| 89 | \begin{classdesc}{WeakValueDictionary}{\optional{dict}} |
Fred Drake | ac154a1 | 2001-04-10 19:57:58 +0000 | [diff] [blame] | 90 | Mapping class that references values weakly. Entries in the |
| 91 | dictionary will be discarded when no strong reference to the value |
| 92 | exists anymore. |
Fred Drake | ebcf6a8 | 2001-02-01 05:20:20 +0000 | [diff] [blame] | 93 | \end{classdesc} |
| 94 | |
| 95 | \begin{datadesc}{ReferenceType} |
| 96 | The type object for weak references objects. |
| 97 | \end{datadesc} |
| 98 | |
| 99 | \begin{datadesc}{ProxyType} |
| 100 | The type object for proxies of objects which are not callable. |
| 101 | \end{datadesc} |
| 102 | |
| 103 | \begin{datadesc}{CallableProxyType} |
| 104 | The type object for proxies of callable objects. |
| 105 | \end{datadesc} |
| 106 | |
| 107 | \begin{datadesc}{ProxyTypes} |
| 108 | Sequence containing all the type objects for proxies. This can make |
| 109 | it simpler to test if an object is a proxy without being dependent |
| 110 | on naming both proxy types. |
| 111 | \end{datadesc} |
| 112 | |
Fred Drake | ac154a1 | 2001-04-10 19:57:58 +0000 | [diff] [blame] | 113 | \begin{excdesc}{ReferenceError} |
| 114 | Exception raised when a proxy object is used but the underlying |
Fred Drake | 8c2c3d3 | 2001-10-06 06:10:54 +0000 | [diff] [blame] | 115 | object has been collected. This is the same as the standard |
| 116 | \exception{ReferenceError} exception. |
Fred Drake | ac154a1 | 2001-04-10 19:57:58 +0000 | [diff] [blame] | 117 | \end{excdesc} |
| 118 | |
Fred Drake | ebcf6a8 | 2001-02-01 05:20:20 +0000 | [diff] [blame] | 119 | |
| 120 | \begin{seealso} |
| 121 | \seepep{0205}{Weak References}{The proposal and rationale for this |
| 122 | feature, including links to earlier implementations |
| 123 | and information about similar features in other |
| 124 | languages.} |
| 125 | \end{seealso} |
| 126 | |
| 127 | |
| 128 | \subsection{Weak Reference Objects |
| 129 | \label{weakref-objects}} |
| 130 | |
| 131 | Weak reference objects have no attributes or methods, but do allow the |
| 132 | referent to be obtained, if it still exists, by calling it: |
| 133 | |
| 134 | \begin{verbatim} |
| 135 | >>> import weakref |
| 136 | >>> class Object: |
| 137 | ... pass |
| 138 | ... |
| 139 | >>> o = Object() |
| 140 | >>> r = weakref.ref(o) |
| 141 | >>> o2 = r() |
| 142 | >>> o is o2 |
| 143 | 1 |
| 144 | \end{verbatim} |
| 145 | |
| 146 | If the referent no longer exists, calling the reference object returns |
| 147 | \code{None}: |
| 148 | |
| 149 | \begin{verbatim} |
| 150 | >>> del o, o2 |
| 151 | >>> print r() |
| 152 | None |
| 153 | \end{verbatim} |
| 154 | |
| 155 | Testing that a weak reference object is still live should be done |
Fred Drake | 5d54879 | 2001-08-03 03:50:28 +0000 | [diff] [blame] | 156 | using the expression \code{\var{ref}() is not None}. Normally, |
Fred Drake | ebcf6a8 | 2001-02-01 05:20:20 +0000 | [diff] [blame] | 157 | application code that needs to use a reference object should follow |
| 158 | this pattern: |
| 159 | |
| 160 | \begin{verbatim} |
Fred Drake | 5d54879 | 2001-08-03 03:50:28 +0000 | [diff] [blame] | 161 | o = ref() |
Fred Drake | ebcf6a8 | 2001-02-01 05:20:20 +0000 | [diff] [blame] | 162 | if o is None: |
| 163 | # referent has been garbage collected |
| 164 | print "Object has been allocated; can't frobnicate." |
| 165 | else: |
| 166 | print "Object is still live!" |
| 167 | o.do_something_useful() |
| 168 | \end{verbatim} |
| 169 | |
| 170 | Using a separate test for ``liveness'' creates race conditions in |
| 171 | threaded applications; another thread can cause a weak reference to |
| 172 | become invalidated before the \method{get()} method is called; the |
| 173 | idiom shown above is safe in threaded applications as well as |
| 174 | single-threaded applications. |
| 175 | |
| 176 | |
Fred Drake | cb83988 | 2001-03-28 21:15:41 +0000 | [diff] [blame] | 177 | \subsection{Example \label{weakref-example}} |
| 178 | |
| 179 | This simple example shows how an application can use objects IDs to |
| 180 | retrieve objects that it has seen before. The IDs of the objects can |
| 181 | then be used in other data structures without forcing the objects to |
| 182 | remain alive, but the objects can still be retrieved by ID if they |
| 183 | do. |
| 184 | |
| 185 | % Example contributed by Tim Peters <tim_one@msn.com>. |
| 186 | \begin{verbatim} |
| 187 | import weakref |
| 188 | |
Fred Drake | ac154a1 | 2001-04-10 19:57:58 +0000 | [diff] [blame] | 189 | _id2obj_dict = weakref.WeakValueDictionary() |
Fred Drake | cb83988 | 2001-03-28 21:15:41 +0000 | [diff] [blame] | 190 | |
| 191 | def remember(obj): |
| 192 | _id2obj_dict[id(obj)] = obj |
| 193 | |
| 194 | def id2obj(id): |
Fred Drake | 5d54879 | 2001-08-03 03:50:28 +0000 | [diff] [blame] | 195 | return _id2obj_dict(id) |
Fred Drake | cb83988 | 2001-03-28 21:15:41 +0000 | [diff] [blame] | 196 | \end{verbatim} |
| 197 | |
| 198 | |
Fred Drake | ebcf6a8 | 2001-02-01 05:20:20 +0000 | [diff] [blame] | 199 | \subsection{Weak References in Extension Types |
| 200 | \label{weakref-extension}} |
| 201 | |
| 202 | One of the goals of the implementation is to allow any type to |
| 203 | participate in the weak reference mechanism without incurring the |
| 204 | overhead on those objects which do not benefit by weak referencing |
| 205 | (such as numbers). |
| 206 | |
| 207 | For an object to be weakly referencable, the extension must include a |
| 208 | \ctype{PyObject *} field in the instance structure for the use of the |
Fred Drake | 5e0dfac | 2001-03-23 04:36:02 +0000 | [diff] [blame] | 209 | weak reference mechanism; it must be initialized to \NULL{} by the |
| 210 | object's constructor. It must also set the \member{tp_weaklistoffset} |
Fred Drake | ebcf6a8 | 2001-02-01 05:20:20 +0000 | [diff] [blame] | 211 | field of the corresponding type object to the offset of the field. |
| 212 | For example, the instance type is defined with the following structure: |
| 213 | |
| 214 | \begin{verbatim} |
| 215 | typedef struct { |
| 216 | PyObject_HEAD |
| 217 | PyClassObject *in_class; /* The class object */ |
Martin v. Löwis | 5e16333 | 2001-02-27 18:36:56 +0000 | [diff] [blame] | 218 | PyObject *in_dict; /* A dictionary */ |
| 219 | PyObject *in_weakreflist; /* List of weak references */ |
Fred Drake | ebcf6a8 | 2001-02-01 05:20:20 +0000 | [diff] [blame] | 220 | } PyInstanceObject; |
| 221 | \end{verbatim} |
| 222 | |
| 223 | The statically-declared type object for instances is defined this way: |
| 224 | |
| 225 | \begin{verbatim} |
| 226 | PyTypeObject PyInstance_Type = { |
| 227 | PyObject_HEAD_INIT(&PyType_Type) |
| 228 | 0, |
| 229 | "instance", |
| 230 | |
Fred Drake | f66cb5d | 2001-06-22 17:20:29 +0000 | [diff] [blame] | 231 | /* Lots of stuff omitted for brevity... */ |
Fred Drake | ebcf6a8 | 2001-02-01 05:20:20 +0000 | [diff] [blame] | 232 | |
| 233 | offsetof(PyInstanceObject, in_weakreflist) /* tp_weaklistoffset */ |
| 234 | }; |
| 235 | \end{verbatim} |
| 236 | |
| 237 | The only further addition is that the destructor needs to call the |
Fred Drake | f66cb5d | 2001-06-22 17:20:29 +0000 | [diff] [blame] | 238 | weak reference manager to clear any weak references. This should be |
| 239 | done before any other parts of the destruction have occurred: |
Fred Drake | ebcf6a8 | 2001-02-01 05:20:20 +0000 | [diff] [blame] | 240 | |
| 241 | \begin{verbatim} |
| 242 | static void |
| 243 | instance_dealloc(PyInstanceObject *inst) |
| 244 | { |
Fred Drake | f66cb5d | 2001-06-22 17:20:29 +0000 | [diff] [blame] | 245 | /* Allocate tempories if needed, but do not begin |
| 246 | destruction just yet. |
Fred Drake | ebcf6a8 | 2001-02-01 05:20:20 +0000 | [diff] [blame] | 247 | */ |
| 248 | |
Fred Drake | f66cb5d | 2001-06-22 17:20:29 +0000 | [diff] [blame] | 249 | PyObject_ClearWeakRefs((PyObject *) inst); |
Fred Drake | ebcf6a8 | 2001-02-01 05:20:20 +0000 | [diff] [blame] | 250 | |
Fred Drake | de3d060 | 2001-10-26 11:27:54 +0000 | [diff] [blame^] | 251 | /* Proceed with object destruction normally. */ |
Fred Drake | ebcf6a8 | 2001-02-01 05:20:20 +0000 | [diff] [blame] | 252 | } |
| 253 | \end{verbatim} |