Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libweakref.tex @ 16413:8819867f14ef legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Patch derived from Trent's 101162: a Python/C API testing framework. STILL NEEDS UNIX BUILD CHANGES.
author Tim Peters <tim.peters@gmail.com>
date Fri, 02 Feb 2001 05:57:15 +0000
parents 48b4acf73ad7
children 56a8106baf63
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1 \section{\module{weakref} ---
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
2 Weak references}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
3
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
4 \declaremodule{extension}{weakref}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
5 \moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
6 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
7
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
8 \versionadded{2.1}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
9
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
10
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
11 The \module{weakref} module allows the Python programmer to create
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
12 \dfn{weak references} to objects.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
13
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
14 XXX --- need to say more here!
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
15
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
16 Not all objects can be weakly referenced; those objects which do
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
17 include class instances and dictionaries. Extension types can easily
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
18 be made to support weak references; see section \ref{weakref-extension},
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
19 ``Weak References in Extension Types,'' for more information.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
20
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
21
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
22 \strong{Warning:}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
23 The weak dictionaries provided in the current implementation and
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
24 described below are subject to change. They are included to solicit
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
25 feedback and usage experience, and may be changed or removed in the
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
26 final version.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
27
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
28 \strong{Warning:}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
29 The desired semantics of weak-reference proxy objects are not
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
30 completely clear; it is very difficult to create proxies which behave
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
31 exactly like the type of the referent. The details of these objects
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
32 are likely to change to some degree before the final release as
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
33 experience reports become available.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
34
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
35 Please send specific feeback on this module to Fred Drake at
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
36 \email{fdrake@acm.org}.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
37
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
38
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
39 \begin{funcdesc}{ref}{object\optional{, callback}}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
40 Return a weak reference to \var{object}. If \var{callback} is
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
41 provided, it will be called when the object is about to be
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
42 finalized; the weak reference object will be passed as the only
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
43 parameter to the callback; the referent will no longer be available.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
44 The original object can be retrieved by calling the reference
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
45 object, if the referent is still alive.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
46
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
47 It is allowable for many weak references to be constructed for the
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
48 same object. Callbacks registered for each weak reference will be
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
49 called from the most recently registered callback to the oldest
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
50 registered callback.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
51
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
52 Exceptions raised by the callback will be noted on the standard
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
53 error output, but cannot be propogated; they are handled in exactly
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
54 the same way as exceptions raised from an object's
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
55 \method{__del__()} method.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
56 \end{funcdesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
57
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
58 \begin{funcdesc}{mapping}{\optional{dict}}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
59 Return a weak dictionary. If \var{dict} is given and not
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
60 \code{None}, the new dictionary will contain the items contained in
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
61 \var{dict}. The values from \var{dict} must be weakly referencable;
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
62 if any values which would be inserted into the new mapping are not
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
63 weakly referencable, \exception{TypeError} will be raised and the
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
64 new mapping will be empty.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
65 \end{funcdesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
66
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
67 \begin{funcdesc}{proxy}{object\optional{, callback}}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
68 Return a proxy to \var{object} which uses a weak reference. This
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
69 supports use of the proxy in most contexts instead of requiring the
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
70 explicit dereferencing used with weak reference objects. The
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
71 returned object will have a type of either \code{ProxyType} or
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
72 \code{CallableProxyType}, depending on whether \var{object} is
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
73 callable. Proxy objects are not hashable regardless of the
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
74 referent; this avoids a number of problems related to their
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
75 fundamentally mutable nature, and prevent their use as dictionary
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
76 keys. \var{callable} is the same as the parameter of the same name
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
77 to the \function{ref()} function.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
78 \end{funcdesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
79
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
80 \begin{funcdesc}{getweakrefcount}{object}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
81 Return the number of weak references and proxies which refer to
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
82 \var{object}.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
83 \end{funcdesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
84
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
85 \begin{funcdesc}{getweakrefs}{object}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
86 Return a list of all weak reference and proxy objects which refer to
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
87 \var{object}.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
88 \end{funcdesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
89
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
90 \begin{classdesc}{WeakDictionary}{\optional{dict}}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
91 The class of the mapping objects returned by \function{mapping()}.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
92 This can be used for subclassing the implementation if needed.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
93 \end{classdesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
94
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
95 \begin{datadesc}{ReferenceType}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
96 The type object for weak references objects.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
97 \end{datadesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
98
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
99 \begin{datadesc}{ProxyType}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
100 The type object for proxies of objects which are not callable.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
101 \end{datadesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
102
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
103 \begin{datadesc}{CallableProxyType}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
104 The type object for proxies of callable objects.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
105 \end{datadesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
106
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
107 \begin{datadesc}{ProxyTypes}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
108 Sequence containing all the type objects for proxies. This can make
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
109 it simpler to test if an object is a proxy without being dependent
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
110 on naming both proxy types.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
111 \end{datadesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
112
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
113
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
114 \begin{seealso}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
115 \seepep{0205}{Weak References}{The proposal and rationale for this
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
116 feature, including links to earlier implementations
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
117 and information about similar features in other
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
118 languages.}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
119 \end{seealso}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
120
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
121
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
122 \subsection{Weak Reference Objects
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
123 \label{weakref-objects}}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
124
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
125 Weak reference objects have no attributes or methods, but do allow the
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
126 referent to be obtained, if it still exists, by calling it:
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
127
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
128 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
129 >>> import weakref
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
130 >>> class Object:
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
131 ... pass
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
132 ...
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
133 >>> o = Object()
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
134 >>> r = weakref.ref(o)
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
135 >>> o2 = r()
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
136 >>> o is o2
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
137 1
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
138 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
139
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
140 If the referent no longer exists, calling the reference object returns
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
141 \code{None}:
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
142
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
143 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
144 >>> del o, o2
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
145 >>> print r()
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
146 None
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
147 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
148
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
149 Testing that a weak reference object is still live should be done
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
150 using the expression \code{\var{ref}.get() is not None}. Normally,
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
151 application code that needs to use a reference object should follow
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
152 this pattern:
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
153
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
154 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
155 o = ref.get()
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
156 if o is None:
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
157 # referent has been garbage collected
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
158 print "Object has been allocated; can't frobnicate."
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
159 else:
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
160 print "Object is still live!"
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
161 o.do_something_useful()
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
162 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
163
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
164 Using a separate test for ``liveness'' creates race conditions in
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
165 threaded applications; another thread can cause a weak reference to
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
166 become invalidated before the \method{get()} method is called; the
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
167 idiom shown above is safe in threaded applications as well as
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
168 single-threaded applications.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
169
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
170
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
171 \subsection{Weak References in Extension Types
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
172 \label{weakref-extension}}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
173
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
174 One of the goals of the implementation is to allow any type to
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
175 participate in the weak reference mechanism without incurring the
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
176 overhead on those objects which do not benefit by weak referencing
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
177 (such as numbers).
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
178
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
179 For an object to be weakly referencable, the extension must include a
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
180 \ctype{PyObject *} field in the instance structure for the use of the
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
181 weak reference mechanism; it will be initialized by Python's functions
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
182 for object creation. It must also set the \code{tp_weaklistoffset}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
183 field of the corresponding type object to the offset of the field.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
184 For example, the instance type is defined with the following structure:
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
185
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
186 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
187 typedef struct {
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
188 PyObject_HEAD
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
189 PyClassObject *in_class; /* The class object */
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
190 PyObject *in_dict; /* A dictionary */
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
191 PyObject *in_weakreflist; /* List of weak references */
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
192 } PyInstanceObject;
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
193 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
194
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
195 The statically-declared type object for instances is defined this way:
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
196
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
197 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
198 PyTypeObject PyInstance_Type = {
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
199 PyObject_HEAD_INIT(&PyType_Type)
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
200 0,
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
201 "instance",
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
202
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
203 /* lots of stuff omitted for brevity */
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
204
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
205 offsetof(PyInstanceObject, in_weakreflist) /* tp_weaklistoffset */
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
206 };
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
207 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
208
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
209 The only further addition is that the destructor needs to call the
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
210 weak reference manager to clear any weak references and return if the
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
211 object has been resurrected. This needs to occur before any other
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
212 parts of the destruction have occurred:
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
213
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
214 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
215 static void
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
216 instance_dealloc(PyInstanceObject *inst)
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
217 {
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
218 /* allocate tempories if needed, but do not begin
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
219 destruction here
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
220 */
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
221
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
222 if (!PyObject_ClearWeakRefs((PyObject *) inst))
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
223 return;
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
224
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
225 /* proceed with object destuction normally */
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
226 }
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
227 \end{verbatim}