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

annotate Doc/lib/libweakref.tex @ 17322:bd110eadc19a legacy-trunk

One-liner critical fix from Jim Fulton: Eric's string-method crusade got the order backwards in a line (for .find()).

author	Tim Peters <tim.peters@gmail.com>
date	Thu, 05 Apr 2001 22:26:23 +0000
parents	a340ba4aac27
children	471ce0faa775

rev	line source
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	1 \section{\module{weakref} ---
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	2 Weak references}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	3
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	4 \declaremodule{extension}{weakref}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	5 \moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
16794 29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	6 \moduleauthor{Neil Schemenauer}{nas@arctrix.com}
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	7 \moduleauthor{Martin von L\o"wis}{martin@loewis.home.cs.tu-berlin.de}
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	8 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	9
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	10 \versionadded{2.1}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	11
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 The \module{weakref} module allows the Python programmer to create
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	14 \dfn{weak references} to objects.
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	15
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	16 XXX --- need to say more here!
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	17
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	18 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	19 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	20 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	21 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	22 ``Weak References in Extension Types,'' for more information.
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	23
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	24
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	25 \begin{funcdesc}{ref}{object\optional{, callback}}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	26 Return a weak reference to \var{object}. If \var{callback} is
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	27 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	28 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	29 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	30 The original object can be retrieved by calling the reference
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	31 object, if the referent is still alive.
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	32
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	33 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	34 same object. Callbacks registered for each weak reference will be
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	35 called from the most recently registered callback to the oldest
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	36 registered callback.
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 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	39 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	40 the same way as exceptions raised from an object's
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	41 \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	42
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	43 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	44 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	45 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	46 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	47 \exception{TypeError}.
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	48
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	49 Weak references support test for equality, but not ordering. If the
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	50 \var{object} is still alive, to references are equal if the objects
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	51 are equal (regardless of the \var{callback}). If the \var{object}
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	52 has been deleted, they are equal iff they are identical.
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	53 \end{funcdesc}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	54
16794 29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	55 \begin{funcdesc}{mapping}{\optional{dict\optional{, weakkeys=0}}}
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	56 Return a weak dictionary. If \var{dict} is given and not
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	57 \code{None}, the new dictionary will contain the items contained in
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	58 \var{dict}. The values from \var{dict} must be weakly referencable;
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	59 if any values which would be inserted into the new mapping are not
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	60 weakly referencable, \exception{TypeError} will be raised and the
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	61 new mapping will be empty.
16794 29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	62
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	63 If the \var{weakkeys} argument is not given or zero, the values in
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	64 the dictionary are weak. That means the entries in the dictionary
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	65 will be discarded when no strong reference to the value exists
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	66 anymore.
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	67
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	68 If the \var{weakkeys} argument is nonzero, the keys in the
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	69 dictionary are weak, i.e. the entry in the dictionary is discarded
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	70 when the last strong reference to the key is discarded.
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	71 \end{funcdesc}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	72
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	73 \begin{funcdesc}{proxy}{object\optional{, callback}}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	74 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	75 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	76 explicit dereferencing used with weak reference objects. The
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	77 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	78 \code{CallableProxyType}, depending on whether \var{object} is
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	79 callable. Proxy objects are not hashable regardless of the
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	80 referent; this avoids a number of problems related to their
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	81 fundamentally mutable nature, and prevent their use as dictionary
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	82 keys. \var{callable} is the same as the parameter of the same name
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	83 to the \function{ref()} function.
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	84 \end{funcdesc}
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 \begin{funcdesc}{getweakrefcount}{object}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	87 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	88 \var{object}.
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	89 \end{funcdesc}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	90
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	91 \begin{funcdesc}{getweakrefs}{object}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	92 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	93 \var{object}.
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	94 \end{funcdesc}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	95
16794 29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	96 \begin{classdesc}{WeakKeyDictionary}{\optional{dict}}
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	97 The class of the mapping objects returned by \function{mapping()}
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	98 when \var{weakkeys} is true. This can be used for subclassing the
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	99 implementation if needed.
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	100 \end{classdesc}
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	101
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	102 \begin{classdesc}{WeakValueDictionary}{\optional{dict}}
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	103 The class of the mapping objects returned by \function{mapping()}
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	104 when \var{weakkeys} if false. This can be used for subclassing the
29aa832b8787 Patch #403985: Add support for weak-keyed dictionaries Martin v. Löwis <martin@v.loewis.de> parents: 16588 diff changeset	105 implementation if needed.
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	106 \end{classdesc}
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}{ReferenceType}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	109 The type object for weak references 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}{ProxyType}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	113 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	114 \end{datadesc}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	115
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	116 \begin{datadesc}{CallableProxyType}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	117 The type object for proxies of callable objects.
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	118 \end{datadesc}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	119
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	120 \begin{datadesc}{ProxyTypes}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	121 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	122 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	123 on naming both proxy types.
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	124 \end{datadesc}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	125
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{seealso}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	128 \seepep{0205}{Weak References}{The proposal and rationale for this
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	129 feature, including links to earlier implementations
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	130 and information about similar features in other
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	131 languages.}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	132 \end{seealso}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	133
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	134
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	135 \subsection{Weak Reference Objects
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	136 \label{weakref-objects}}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	137
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	138 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	139 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	140
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	141 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	142 >>> import weakref
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	143 >>> class Object:
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	144 ... pass
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	145 ...
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	146 >>> o = Object()
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	147 >>> r = weakref.ref(o)
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	148 >>> o2 = r()
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	149 >>> o is o2
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	150 1
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	151 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	152
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	153 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	154 \code{None}:
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	155
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	156 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	157 >>> del o, o2
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	158 >>> print r()
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	159 None
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	160 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	161
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	162 Testing that a weak reference object is still live should be done
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	163 using the expression \code{\var{ref}.get() is not None}. Normally,
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	164 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	165 this pattern:
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	166
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	167 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	168 o = ref.get()
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	169 if o is None:
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	170 # referent has been garbage collected
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	171 print "Object has been allocated; can't frobnicate."
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	172 else:
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	173 print "Object is still live!"
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	174 o.do_something_useful()
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	175 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	176
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	177 Using a separate test for ``liveness'' creates race conditions in
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	178 threaded applications; another thread can cause a weak reference to
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	179 become invalidated before the \method{get()} method is called; the
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	180 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	181 single-threaded applications.
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	182
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	183
17243 a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	184 \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	185
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	186 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	187 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	188 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	189 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	190 do.
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	191
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	192 % 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	193 \begin{verbatim}
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	194 import weakref
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	195
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	196 _id2obj_dict = weakref.mapping()
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	197
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	198 def remember(obj):
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	199 _id2obj_dict[id(obj)] = obj
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	200
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	201 def id2obj(id):
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	202 return _id2obj_dict.get(id)
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	203 \end{verbatim}
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	204
a340ba4aac27 Added example use of weak references, contributed by Tim Peters. Fred Drake <fdrake@acm.org> parents: 17173 diff changeset	205
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	206 \subsection{Weak References in Extension Types
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	207 \label{weakref-extension}}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	208
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	209 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	210 participate in the weak reference mechanism without incurring the
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	211 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	212 (such as numbers).
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	213
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	214 For an object to be weakly referencable, the extension must include a
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	215 \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	216 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	217 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	218 field of the corresponding type object to the offset of the field.
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	219 For example, the instance type is defined with the following structure:
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	220
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	221 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	222 typedef struct {
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	223 PyObject_HEAD
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	224 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	225 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	226 PyObject in_weakreflist; / List of weak references */
16381 48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	227 } PyInstanceObject;
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	228 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	229
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	230 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	231
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	232 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	233 PyTypeObject PyInstance_Type = {
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	234 PyObject_HEAD_INIT(&PyType_Type)
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	235 0,
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	236 "instance",
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	237
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	238 /* lots of stuff omitted for brevity */
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	239
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	240 offsetof(PyInstanceObject, in_weakreflist) /* tp_weaklistoffset */
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	241 };
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	242 \end{verbatim}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	243
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	244 The only further addition is that the destructor needs to call the
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	245 weak reference manager to clear any weak references and return if the
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	246 object has been resurrected. This needs to occur before any other
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	247 parts of the destruction have occurred:
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	248
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	249 \begin{verbatim}
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	250 static void
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	251 instance_dealloc(PyInstanceObject *inst)
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	252 {
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	253 /* allocate tempories if needed, but do not begin
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	254 destruction here
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	255 */
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	256
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	257 if (!PyObject_ClearWeakRefs((PyObject *) inst))
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	258 return;
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	259
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	260 /* proceed with object destuction normally */
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	261 }
48b4acf73ad7 Documentation for the weakref module. Fred Drake <fdrake@acm.org> parents: diff changeset	262 \end{verbatim}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libweakref.tex @ 17322:bd110eadc19a legacy-trunk