cpython-lru_cache-weakref: Doc/lib/libweakref.tex annotate

annotate Doc/lib/libweakref.tex @ 25838:8540887bcec6 2.2

Backport of 2.183: Fix memory leak in add_subclass() found by NealN with valgrind.

author	Guido van Rossum <guido@python.org>
date	Fri, 18 Oct 2002 13:42:21 +0000
parents	27da2b81a496
children	32f96bac2113

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
20697 648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert. Fred Drake <fdrake@acm.org> parents: 20687 diff changeset	17 In the discussion which follows, the term \dfn{referent} means the
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
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	20 XXX --- need to say more here!
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 Not all objects can be weakly referenced; those objects which do
17173 73f41b0ff777 Update to the most recent weakref changes. Fred Drake <fdrake@acm.org> parents: 16794 diff changeset	23 include class instances, functions written in Python (but not in C),
73f41b0ff777 Update to the most recent weakref changes. Fred Drake <fdrake@acm.org> parents: 16794 diff changeset	24 and methods (both bound and unbound). Extension types can easily
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	25 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	26 ``Weak References in Extension Types,'' for more information.
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
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	29 \begin{funcdesc}{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	30 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	31 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	32 alive; if the referent is no longer alive, calling the reference
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert. Fred Drake <fdrake@acm.org> parents: 20687 diff changeset	33 object will cause \code{None} to be returned. If \var{callback} is
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	34 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	35 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	36 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	37
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	38 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	39 same object. Callbacks registered for each weak reference will be
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	40 called from the most recently registered callback to the oldest
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	41 registered callback.
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	42
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	43 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	44 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	45 the same way as exceptions raised from an object's
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	46 \method{__del__()} method.
16794 29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	47
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	48 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	49 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	50 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	51 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	52 \exception{TypeError}.
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	53
20676 ae94b5f7dd30 Minor textual adjustment, and style-guide conformance (no use of "iff"). Fred Drake <fdrake@acm.org> parents: 20290 diff changeset	54 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	55 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	56 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	57 \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	58 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	59 object.
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	60 \end{funcdesc}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	61
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	62 \begin{funcdesc}{proxy}{object\optional{, callback}}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	63 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	64 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	65 explicit dereferencing used with weak reference objects. The
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	66 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	67 \code{CallableProxyType}, depending on whether \var{object} is
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	68 callable. Proxy objects are not hashable regardless of the
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	69 referent; this avoids a number of problems related to their
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	70 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	71 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	72 to the \function{ref()} function.
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	73 \end{funcdesc}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	74
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	75 \begin{funcdesc}{getweakrefcount}{object}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	76 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	77 \var{object}.
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}{getweakrefs}{object}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	81 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	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
16794 29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	85 \begin{classdesc}{WeakKeyDictionary}{\optional{dict}}
17389 471ce0faa775 Remove the mapping() function from the documentation. Fred Drake <fdrake@acm.org> parents: 17243 diff changeset	86 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	87 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	88 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	89 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	90 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	91 objects that override attribute accesses.
16794 29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	92 \end{classdesc}
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	93
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	94 \begin{classdesc}{WeakValueDictionary}{\optional{dict}}
17389 471ce0faa775 Remove the mapping() function from the documentation. Fred Drake <fdrake@acm.org> parents: 17243 diff changeset	95 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	96 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	97 exists any more.
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	98 \end{classdesc}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	99
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	100 \begin{datadesc}{ReferenceType}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	101 The type object for weak references objects.
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	102 \end{datadesc}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	103
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	104 \begin{datadesc}{ProxyType}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	105 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	106 \end{datadesc}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	107
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	108 \begin{datadesc}{CallableProxyType}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	109 The type object for proxies of callable objects.
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	110 \end{datadesc}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	111
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	112 \begin{datadesc}{ProxyTypes}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	113 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	114 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	115 on naming both proxy types.
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	116 \end{datadesc}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	117
17389 471ce0faa775 Remove the mapping() function from the documentation. Fred Drake <fdrake@acm.org> parents: 17243 diff changeset	118 \begin{excdesc}{ReferenceError}
471ce0faa775 Remove the mapping() function from the documentation. Fred Drake <fdrake@acm.org> parents: 17243 diff changeset	119 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	120 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	121 \exception{ReferenceError} exception.
17389 471ce0faa775 Remove the mapping() function from the documentation. Fred Drake <fdrake@acm.org> parents: 17243 diff changeset	122 \end{excdesc}
471ce0faa775 Remove the mapping() function from the documentation. Fred Drake <fdrake@acm.org> parents: 17243 diff changeset	123
16381 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 \begin{seealso}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	126 \seepep{0205}{Weak References}{The proposal and rationale for this
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	127 feature, including links to earlier implementations
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	128 and information about similar features in other
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	129 languages.}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	130 \end{seealso}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	131
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 \subsection{Weak Reference Objects
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	134 \label{weakref-objects}}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	135
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	136 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	137 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	138
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	139 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	140 >>> import weakref
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	141 >>> class Object:
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	142 ... pass
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	143 ...
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	144 >>> o = Object()
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	145 >>> r = weakref.ref(o)
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	146 >>> o2 = r()
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	147 >>> o is o2
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	148 1
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	149 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	150
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	151 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	152 \code{None}:
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 >>> del o, o2
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	156 >>> print r()
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	157 None
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	158 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	159
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	160 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	161 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	162 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	163 this pattern:
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{verbatim}
20697 648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert. Fred Drake <fdrake@acm.org> parents: 20687 diff changeset	166 # 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	167 o = r()
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	168 if o is None:
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	169 # referent has been garbage collected
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	170 print "Object has been allocated; can't frobnicate."
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	171 else:
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	172 print "Object is still live!"
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	173 o.do_something_useful()
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	174 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	175
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	176 Using a separate test for ``liveness'' creates race conditions in
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	177 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	178 become invalidated before the weak reference is called; the
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	179 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	180 single-threaded applications.
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	181
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	182
17243 a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	183 \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	184
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	185 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	186 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	187 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	188 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	189 do.
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	190
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	191 % Example contributed by Tim Peters <tim_one@msn.com>.
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	192 \begin{verbatim}
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	193 import weakref
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	194
17389 471ce0faa775 Remove the mapping() function from the documentation. Fred Drake <fdrake@acm.org> parents: 17243 diff changeset	195 _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	196
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	197 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	198 oid = id(obj)
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert. Fred Drake <fdrake@acm.org> parents: 20687 diff changeset	199 _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	200 return oid
17243 a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	201
20697 648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert. Fred Drake <fdrake@acm.org> parents: 20687 diff changeset	202 def id2obj(oid):
648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert. Fred Drake <fdrake@acm.org> parents: 20687 diff changeset	203 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	204 \end{verbatim}
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	205
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	206
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	207 \subsection{Weak References in Extension Types
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	208 \label{weakref-extension}}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	209
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	210 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	211 participate in the weak reference mechanism without incurring the
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	212 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	213 (such as numbers).
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 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	216 \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	217 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	218 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	219 field of the corresponding type object to the offset of the field.
24643 27da2b81a496 Described responsibilty of weakly referenced extension types to initialize Raymond Hettinger <python@rcn.com> parents: 21313 diff changeset	220 Also, it needs to add \constant{Py_TPFLAGS_HAVE_WEAKREFS} to the
27da2b81a496 Described responsibilty of weakly referenced extension types to initialize Raymond Hettinger <python@rcn.com> parents: 21313 diff changeset	221 tp_flags slot. For example, the instance type is defined with the
27da2b81a496 Described responsibilty of weakly referenced extension types to initialize Raymond Hettinger <python@rcn.com> parents: 21313 diff changeset	222 following structure:
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	223
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	224 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	225 typedef struct {
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	226 PyObject_HEAD
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	227 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	228 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	229 PyObject in_weakreflist; / List of weak references */
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	230 } PyInstanceObject;
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	231 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	232
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	233 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	234
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	235 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	236 PyTypeObject PyInstance_Type = {
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	237 PyObject_HEAD_INIT(&PyType_Type)
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	238 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	239 "module.instance",
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	240
18223 220405c07232 Corrected an error in the information on supporting weak references in Fred Drake <fdrake@acm.org> parents: 17768 diff changeset	241 /* Lots of stuff omitted for brevity... */
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	242
24643 27da2b81a496 Described responsibilty of weakly referenced extension types to initialize Raymond Hettinger <python@rcn.com> parents: 21313 diff changeset	243 Py_TPFLAGS_DEFAULT \| Py_TPFLAGS_HAVE_WEAKREFS /* tp_flags */
27da2b81a496 Described responsibilty of weakly referenced extension types to initialize Raymond Hettinger <python@rcn.com> parents: 21313 diff changeset	244 0, /* tp_doc */
27da2b81a496 Described responsibilty of weakly referenced extension types to initialize Raymond Hettinger <python@rcn.com> parents: 21313 diff changeset	245 0, /* tp_traverse */
27da2b81a496 Described responsibilty of weakly referenced extension types to initialize Raymond Hettinger <python@rcn.com> parents: 21313 diff changeset	246 0, /* tp_clear */
27da2b81a496 Described responsibilty of weakly referenced extension types to initialize Raymond Hettinger <python@rcn.com> parents: 21313 diff changeset	247 0, /* tp_richcompare */
27da2b81a496 Described responsibilty of weakly referenced extension types to initialize Raymond Hettinger <python@rcn.com> parents: 21313 diff changeset	248 offsetof(PyInstanceObject, in_weakreflist), /* tp_weaklistoffset */
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	249 };
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	250 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	251
24643 27da2b81a496 Described responsibilty of weakly referenced extension types to initialize Raymond Hettinger <python@rcn.com> parents: 21313 diff changeset	252 The type constructor is responsible for initializing the weak reference
27da2b81a496 Described responsibilty of weakly referenced extension types to initialize Raymond Hettinger <python@rcn.com> parents: 21313 diff changeset	253 list to \NULL:
27da2b81a496 Described responsibilty of weakly referenced extension types to initialize Raymond Hettinger <python@rcn.com> parents: 21313 diff changeset	254
27da2b81a496 Described responsibilty of weakly referenced extension types to initialize Raymond Hettinger <python@rcn.com> parents: 21313 diff changeset	255 \begin{verbatim}
27da2b81a496 Described responsibilty of weakly referenced extension types to initialize Raymond Hettinger <python@rcn.com> parents: 21313 diff changeset	256 static PyObject *
27da2b81a496 Described responsibilty of weakly referenced extension types to initialize Raymond Hettinger <python@rcn.com> parents: 21313 diff changeset	257 instance_new() {
27da2b81a496 Described responsibilty of weakly referenced extension types to initialize Raymond Hettinger <python@rcn.com> parents: 21313 diff changeset	258 /* Other initialization stuff omitted for brevity */
27da2b81a496 Described responsibilty of weakly referenced extension types to initialize Raymond Hettinger <python@rcn.com> parents: 21313 diff changeset	259
27da2b81a496 Described responsibilty of weakly referenced extension types to initialize Raymond Hettinger <python@rcn.com> parents: 21313 diff changeset	260 self->in_weakreflist = NULL;
27da2b81a496 Described responsibilty of weakly referenced extension types to initialize Raymond Hettinger <python@rcn.com> parents: 21313 diff changeset	261
27da2b81a496 Described responsibilty of weakly referenced extension types to initialize Raymond Hettinger <python@rcn.com> parents: 21313 diff changeset	262 return (PyObject *) self;
27da2b81a496 Described responsibilty of weakly referenced extension types to initialize Raymond Hettinger <python@rcn.com> parents: 21313 diff changeset	263 }
27da2b81a496 Described responsibilty of weakly referenced extension types to initialize Raymond Hettinger <python@rcn.com> parents: 21313 diff changeset	264 \end{verbatim}
27da2b81a496 Described responsibilty of weakly referenced extension types to initialize Raymond Hettinger <python@rcn.com> parents: 21313 diff changeset	265
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	266 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	267 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	268 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	269 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	270
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	271 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	272 static void
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	273 instance_dealloc(PyInstanceObject *inst)
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	274 {
20697 648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert. Fred Drake <fdrake@acm.org> parents: 20687 diff changeset	275 /* 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	276 destruction just yet.
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	277 */
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	278
20697 648bc74c47ab Many, many small fixes and improvements, most suggested by Detlef Lannert. Fred Drake <fdrake@acm.org> parents: 20687 diff changeset	279 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	280 PyObject_ClearWeakRefs((PyObject *) inst);
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	281
20687 367cd8e5df47 Typo: destuction --> destruction Fred Drake <fdrake@acm.org> parents: 20676 diff changeset	282 /* Proceed with object destruction normally. */
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	283 }
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	284 \end{verbatim}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libweakref.tex @ 25838:8540887bcec6 2.2