Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libweakref.tex @ 32527:0da660e05e69 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
"#if WITH_THREAD" is incorrect; must be #ifdef instead; WITH_THREAD isn't always set to an integer value when it's defined.
author Tim Peters <tim.peters@gmail.com>
date Wed, 07 Jul 2004 20:42:07 +0000
parents 4383db77b19a
children 8f7e47a0aaca
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}
17414
4c497c5e72ad Include a synopsis for the chapter overview.
Fred Drake <fdrake@acm.org>
parents: 17389
diff changeset
5 \modulesynopsis{Support for weak references and weak dictionaries.}
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
6 \moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
16794
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
7 \moduleauthor{Neil Schemenauer}{nas@arctrix.com}
18348
798b5e6b4915 Correct a markup error for an accented character.
Fred Drake <fdrake@acm.org>
parents: 18223
diff changeset
8 \moduleauthor{Martin von L\"owis}{martin@loewis.home.cs.tu-berlin.de}
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
9 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
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 \versionadded{2.1}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
12
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 The \module{weakref} module allows the Python programmer to create
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
15 \dfn{weak references} to objects.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
16
30998
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
17 In the following, the term \dfn{referent} means the
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
18 object which is referred to by a weak reference.
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
19
30998
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
20 A weak reference to an object is not enough to keep the object alive:
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
21 when the only remaining references to a referent are weak references,
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
22 garbage collection is free to destroy the referent and reuse its memory
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
23 for something else. A primary use for weak references is to implement
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
24 caches or mappings holding large objects, where it's desired that a
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
25 large object not be kept alive solely because it appears in a cache or
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
26 mapping. For example, if you have a number of large binary image objects,
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
27 you may wish to associate a name with each. If you used a Python
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
28 dictionary to map names to images, or images to names, the image objects
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
29 would remain alive just because they appeared as values or keys in the
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
30 dictionaries. The \class{WeakKeyDictionary} and
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
31 \class{WeakValueDictionary} classes supplied by the \module{weakref}
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
32 module are an alternative, using weak references to construct mappings
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
33 that don't keep objects alive solely because they appear in the mapping
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
34 objects. If, for example, an image object is a value in a
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
35 \class{WeakValueDictionary}, then when the last remaining
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
36 references to that image object are the weak references held by weak
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
37 mappings, garbage collection can reclaim the object, and its corresponding
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
38 entries in weak mappings are simply deleted.
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
39
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
40 \class{WeakKeyDictionary} and \class{WeakValueDictionary} use weak
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
41 references in their implementation, setting up callback functions on
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
42 the weak references that notify the weak dictionaries when a key or value
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
43 has been reclaimed by garbage collection. Most programs should find that
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
44 using one of these weak dictionary types is all they need -- it's
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
45 not usually necessary to create your own weak references directly. The
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
46 low-level machinery used by the weak dictionary implementations is exposed
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
47 by the \module{weakref} module for the benefit of advanced uses.
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
48
29745
32f96bac2113 Grammar nit. SF bug #757822
Raymond Hettinger <python@rcn.com>
parents: 24642
diff changeset
49 Not all objects can be weakly referenced; those objects which can
17173
73f41b0ff777 Update to the most recent weakref changes.
Fred Drake <fdrake@acm.org>
parents: 16794
diff changeset
50 include class instances, functions written in Python (but not in C),
32160
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
51 methods (both bound and unbound), sets, frozensets, file objects,
32330
541327cb8f8b Complete the list of weakreferencable objects.
Raymond Hettinger <python@rcn.com>
parents: 32160
diff changeset
52 generators, type objects, DBcursor objects from the \module{bsddb} module,
32160
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
53 sockets, arrays, deques, and regular expression pattern objects.
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
54 \versionchanged[Added support for files, sockets, arrays, and patterns]{2.4}
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
55
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
56 Several builtin types such as \class{list} and \class{dict} do not
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
57 directly support weak references but can add support through subclassing:
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
58
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
59 \begin{verbatim}
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
60 class Dict(dict):
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
61 pass
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
62
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
63 obj = Dict(red=1, green=2, blue=3) # this object is weak referencable
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
64 \end{verbatim}
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
65
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
66 Extension types can easily be made to support weak references; see section
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
67 \ref{weakref-extension}, ``Weak References in Extension Types,'' for more
aec9c98a47d2 Add weakref support to sockets and re pattern objects.
Raymond Hettinger <python@rcn.com>
parents: 31452
diff changeset
68 information.
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
69
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
70
32472
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
71 \begin{classdesc}{ref}{object\optional{, callback}}
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
72 Return a weak reference to \var{object}. The original object can be
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
73 retrieved by calling the reference object if the referent is still
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
74 alive; if the referent is no longer alive, calling the reference
31452
bb7146d117fb minor markup adjustments
Fred Drake <fdrake@acm.org>
parents: 31446
diff changeset
75 object will cause \constant{None} to be returned. If \var{callback} is
31446
97bcf2e88ceb Clarify minor point about the ref() and proxy() constructors.
Fred Drake <fdrake@acm.org>
parents: 31276
diff changeset
76 provided and not \constant{None},
97bcf2e88ceb Clarify minor point about the ref() and proxy() constructors.
Fred Drake <fdrake@acm.org>
parents: 31276
diff changeset
77 it will be called when the object is about to be
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
78 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
79 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
80
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
81 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
82 same object. Callbacks registered for each weak reference will be
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
83 called from the most recently registered callback to the oldest
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
84 registered callback.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
85
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
86 Exceptions raised by the callback will be noted on the standard
16588
56a8106baf63 Fix two typos
Andrew M. Kuchling <amk@amk.ca>
parents: 16381
diff changeset
87 error output, but cannot be propagated; they are handled in exactly
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
88 the same way as exceptions raised from an object's
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
89 \method{__del__()} method.
30998
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
90
16794
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
91 Weak references are hashable if the \var{object} is hashable. They
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
92 will maintain their hash value even after the \var{object} was
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
93 deleted. If \function{hash()} is called the first time only after
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
94 the \var{object} was deleted, the call will raise
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
95 \exception{TypeError}.
30998
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
96
20676
ae94b5f7dd30 Minor textual adjustment, and style-guide conformance (no use of "iff").
Fred Drake <fdrake@acm.org>
parents: 20290
diff changeset
97 Weak references support tests for equality, but not ordering. If
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
98 the referents are still alive, two references have the same
21054
bcbda606d8c7 Typo, spotted by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20697
diff changeset
99 equality relationship as their referents (regardless of the
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
100 \var{callback}). If either referent has been deleted, the
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
101 references are equal only if the reference objects are the same
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
102 object.
32472
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
103
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
104 \versionchanged[This is now a subclassable type rather than a
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
105 factory function; it derives from \class{object}]
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
106 {2.4}
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
107 \end{classdesc}
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
108
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
109 \begin{funcdesc}{proxy}{object\optional{, callback}}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
110 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
111 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
112 explicit dereferencing used with weak reference objects. The
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
113 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
114 \code{CallableProxyType}, depending on whether \var{object} is
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
115 callable. Proxy objects are not hashable regardless of the
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
116 referent; this avoids a number of problems related to their
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
117 fundamentally mutable nature, and prevent their use as dictionary
17768
c1880f6b3189 Fix typo in weakref.proxy() documentation.
Fred Drake <fdrake@acm.org>
parents: 17414
diff changeset
118 keys. \var{callback} is the same as the parameter of the same name
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
119 to the \function{ref()} function.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
120 \end{funcdesc}
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 \begin{funcdesc}{getweakrefcount}{object}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
123 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
124 \var{object}.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
125 \end{funcdesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
126
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
127 \begin{funcdesc}{getweakrefs}{object}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
128 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
129 \var{object}.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
130 \end{funcdesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
131
16794
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
132 \begin{classdesc}{WeakKeyDictionary}{\optional{dict}}
17389
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
133 Mapping class that references keys weakly. Entries in the
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
134 dictionary will be discarded when there is no longer a strong
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
135 reference to the key. This can be used to associate additional data
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
136 with an object owned by other parts of an application without adding
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
137 attributes to those objects. This can be especially useful with
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
138 objects that override attribute accesses.
30998
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
139
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
140 \note{Caution: Because a \class{WeakKeyDictionary} is built on top
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
141 of a Python dictionary, it must not change size when iterating
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
142 over it. This can be difficult to ensure for a
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
143 \class{WeakKeyDictionary} because actions performed by the
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
144 program during iteration may cause items in the dictionary
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
145 to vanish "by magic" (as a side effect of garbage collection).}
16794
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
146 \end{classdesc}
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
147
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
148 \begin{classdesc}{WeakValueDictionary}{\optional{dict}}
17389
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
149 Mapping class that references values weakly. Entries in the
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
150 dictionary will be discarded when no strong reference to the value
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
151 exists any more.
30998
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
152
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
153 \note{Caution: Because a \class{WeakValueDictionary} is built on top
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
154 of a Python dictionary, it must not change size when iterating
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
155 over it. This can be difficult to ensure for a
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
156 \class{WeakValueDictionary} because actions performed by the
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
157 program during iteration may cause items in the dictionary
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
158 to vanish "by magic" (as a side effect of garbage collection).}
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
159 \end{classdesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
160
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
161 \begin{datadesc}{ReferenceType}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
162 The type object for weak references objects.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
163 \end{datadesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
164
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
165 \begin{datadesc}{ProxyType}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
166 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
167 \end{datadesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
168
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
169 \begin{datadesc}{CallableProxyType}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
170 The type object for proxies of callable objects.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
171 \end{datadesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
172
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
173 \begin{datadesc}{ProxyTypes}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
174 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
175 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
176 on naming both proxy types.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
177 \end{datadesc}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
178
17389
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
179 \begin{excdesc}{ReferenceError}
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
180 Exception raised when a proxy object is used but the underlying
20290
acd8378216c3 Update the documentation to reflect the changes to ReferenceError.
Fred Drake <fdrake@acm.org>
parents: 18951
diff changeset
181 object has been collected. This is the same as the standard
acd8378216c3 Update the documentation to reflect the changes to ReferenceError.
Fred Drake <fdrake@acm.org>
parents: 18951
diff changeset
182 \exception{ReferenceError} exception.
17389
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
183 \end{excdesc}
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
184
16381
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{seealso}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
187 \seepep{0205}{Weak References}{The proposal and rationale for this
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
188 feature, including links to earlier implementations
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
189 and information about similar features in other
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
190 languages.}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
191 \end{seealso}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
192
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
193
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
194 \subsection{Weak Reference Objects
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
195 \label{weakref-objects}}
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 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
198 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
199
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
200 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
201 >>> import weakref
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
202 >>> class Object:
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
203 ... pass
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 >>> o = Object()
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
206 >>> r = weakref.ref(o)
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
207 >>> o2 = r()
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
208 >>> o is o2
31029
ce07118ee5d2 Patch #849350: Update to document bool return values. Backported to 2.3.
Martin v. Löwis <martin@v.loewis.de>
parents: 30998
diff changeset
209 True
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
210 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
211
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
212 If the referent no longer exists, calling the reference object returns
31452
bb7146d117fb minor markup adjustments
Fred Drake <fdrake@acm.org>
parents: 31446
diff changeset
213 \constant{None}:
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
214
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
215 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
216 >>> del o, o2
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
217 >>> print r()
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
218 None
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
219 \end{verbatim}
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 Testing that a weak reference object is still live should be done
18951
f72d61b1246e Fix some of the example code; the reference objects do not support a
Fred Drake <fdrake@acm.org>
parents: 18348
diff changeset
222 using the expression \code{\var{ref}() is not None}. Normally,
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
223 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
224 this pattern:
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
225
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
226 \begin{verbatim}
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
227 # r is a weak reference object
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
228 o = r()
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
229 if o is None:
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
230 # referent has been garbage collected
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
231 print "Object has been allocated; can't frobnicate."
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
232 else:
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
233 print "Object is still live!"
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
234 o.do_something_useful()
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
235 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
236
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
237 Using a separate test for ``liveness'' creates race conditions in
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
238 threaded applications; another thread can cause a weak reference to
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
239 become invalidated before the weak reference is called; the
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
240 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
241 single-threaded applications.
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
242
32472
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
243 Specialized versions of \class{ref} objects can be created through
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
244 subclassing. This is used in the implementation of the
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
245 \class{WeakValueDictionary} to reduce the memory overhead for each
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
246 entry in the mapping. This may be most useful to associate additional
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
247 information with a reference, but could also be used to insert
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
248 additional processing on calls to retrieve the referent.
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
249
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
250 This example shows how a subclass of \class{ref} can be used to store
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
251 additional information about an object and affect the value that's
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
252 returned when the referent is accessed:
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
253
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
254 \begin{verbatim}
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
255 import weakref
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
256
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
257 class ExtendedRef(weakref.ref):
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
258 def __new__(cls, ob, callback=None, **annotations):
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
259 weakref.ref.__new__(cls, ob, callback)
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
260 self.__counter = 0
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
261
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
262 def __init__(self, ob, callback=None, **annotations):
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
263 super(ExtendedRef, self).__init__(ob, callback)
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
264 for k, v in annotations:
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
265 setattr(self, k, v)
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
266
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
267 def __call__(self):
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
268 """Return a pair containing the referent and the number of
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
269 times the reference has been called.
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
270 """
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
271 ob = super(ExtendedRef, self)()
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
272 if ob is not None:
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
273 self.__counter += 1
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
274 ob = (ob, self.__counter)
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
275 return ob
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
276 \end{verbatim}
4383db77b19a Make weak references subclassable:
Fred Drake <fdrake@acm.org>
parents: 32330
diff changeset
277
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
278
17243
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
279 \subsection{Example \label{weakref-example}}
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
280
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
281 This simple example shows how an application can use objects IDs to
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
282 retrieve objects that it has seen before. The IDs of the objects can
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
283 then be used in other data structures without forcing the objects to
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
284 remain alive, but the objects can still be retrieved by ID if they
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
285 do.
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
286
31276
1dc2659ed9fc use consistent email address for Tim
Fred Drake <fdrake@acm.org>
parents: 31029
diff changeset
287 % Example contributed by Tim Peters.
17243
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
288 \begin{verbatim}
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
289 import weakref
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
290
17389
471ce0faa775 Remove the mapping() function from the documentation.
Fred Drake <fdrake@acm.org>
parents: 17243
diff changeset
291 _id2obj_dict = weakref.WeakValueDictionary()
17243
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
292
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
293 def remember(obj):
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
294 oid = id(obj)
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
295 _id2obj_dict[oid] = obj
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
296 return oid
17243
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
297
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
298 def id2obj(oid):
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
299 return _id2obj_dict[oid]
17243
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
300 \end{verbatim}
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
301
a340ba4aac27 Added example use of weak references, contributed by Tim Peters.
Fred Drake <fdrake@acm.org>
parents: 17173
diff changeset
302
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
303 \subsection{Weak References in Extension Types
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
304 \label{weakref-extension}}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
305
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
306 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
307 participate in the weak reference mechanism without incurring the
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
308 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
309 (such as numbers).
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
310
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
311 For an object to be weakly referencable, the extension must include a
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
312 \ctype{PyObject*} field in the instance structure for the use of the
17173
73f41b0ff777 Update to the most recent weakref changes.
Fred Drake <fdrake@acm.org>
parents: 16794
diff changeset
313 weak reference mechanism; it must be initialized to \NULL{} by the
73f41b0ff777 Update to the most recent weakref changes.
Fred Drake <fdrake@acm.org>
parents: 16794
diff changeset
314 object's constructor. It must also set the \member{tp_weaklistoffset}
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
315 field of the corresponding type object to the offset of the field.
24642
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
316 Also, it needs to add \constant{Py_TPFLAGS_HAVE_WEAKREFS} to the
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
317 tp_flags slot. For example, the instance type is defined with the
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
318 following structure:
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
319
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
320 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
321 typedef struct {
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
322 PyObject_HEAD
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
323 PyClassObject *in_class; /* The class object */
16794
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
324 PyObject *in_dict; /* A dictionary */
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries
Martin v. Löwis <martin@v.loewis.de>
parents: 16588
diff changeset
325 PyObject *in_weakreflist; /* List of weak references */
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
326 } PyInstanceObject;
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
327 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
328
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
329 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
330
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
331 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
332 PyTypeObject PyInstance_Type = {
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
333 PyObject_HEAD_INIT(&PyType_Type)
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
334 0,
21313
91dd223829c6 Patch supplied by Burton Radons for his own SF bug #487390: Modifying
Guido van Rossum <guido@python.org>
parents: 21054
diff changeset
335 "module.instance",
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
336
18223
220405c07232 Corrected an error in the information on supporting weak references in
Fred Drake <fdrake@acm.org>
parents: 17768
diff changeset
337 /* Lots of stuff omitted for brevity... */
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
338
24642
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
339 Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_WEAKREFS /* tp_flags */
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
340 0, /* tp_doc */
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
341 0, /* tp_traverse */
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
342 0, /* tp_clear */
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
343 0, /* tp_richcompare */
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
344 offsetof(PyInstanceObject, in_weakreflist), /* tp_weaklistoffset */
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
345 };
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
346 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
347
24642
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
348 The type constructor is responsible for initializing the weak reference
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
349 list to \NULL:
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
350
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
351 \begin{verbatim}
30998
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
352 static PyObject *
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
353 instance_new() {
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
354 /* Other initialization stuff omitted for brevity */
24642
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
355
30998
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
356 self->in_weakreflist = NULL;
24642
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
357
30998
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
358 return (PyObject *) self;
18df203b8e98 More words: gave more motivation, and added cautions about the special
Tim Peters <tim.peters@gmail.com>
parents: 29745
diff changeset
359 }
24642
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
360 \end{verbatim}
a0eb8e382d74 Described responsibilty of weakly referenced extension types to initialize
Raymond Hettinger <python@rcn.com>
parents: 21313
diff changeset
361
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
362 The only further addition is that the destructor needs to call the
18223
220405c07232 Corrected an error in the information on supporting weak references in
Fred Drake <fdrake@acm.org>
parents: 17768
diff changeset
363 weak reference manager to clear any weak references. This should be
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
364 done before any other parts of the destruction have occurred, but is
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
365 only required if the weak reference list is non-\NULL:
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
366
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
367 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
368 static void
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
369 instance_dealloc(PyInstanceObject *inst)
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
370 {
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
371 /* Allocate temporaries if needed, but do not begin
18223
220405c07232 Corrected an error in the information on supporting weak references in
Fred Drake <fdrake@acm.org>
parents: 17768
diff changeset
372 destruction just yet.
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
373 */
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
374
20697
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
375 if (inst->in_weakreflist != NULL)
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert.
Fred Drake <fdrake@acm.org>
parents: 20687
diff changeset
376 PyObject_ClearWeakRefs((PyObject *) inst);
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
377
20687
367cd8e5df47 Typo: destuction --> destruction
Fred Drake <fdrake@acm.org>
parents: 20676
diff changeset
378 /* Proceed with object destruction normally. */
16381
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
379 }
48b4acf73ad7 Documentation for the weakref module.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
380 \end{verbatim}