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