241 lines
8.2 KiB
TeX
241 lines
8.2 KiB
TeX
\section{\module{weakref} ---
|
|
Weak references}
|
|
|
|
\declaremodule{extension}{weakref}
|
|
\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
|
|
\moduleauthor{Neil Schemenauer}{nas@arctrix.com}
|
|
\moduleauthor{Martin von L\o"wis}{martin@loewis.home.cs.tu-berlin.de}
|
|
\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
|
|
|
|
\versionadded{2.1}
|
|
|
|
|
|
The \module{weakref} module allows the Python programmer to create
|
|
\dfn{weak references} to objects.
|
|
|
|
XXX --- need to say more here!
|
|
|
|
Not all objects can be weakly referenced; those objects which do
|
|
include class instances, functions written in Python (but not in C),
|
|
and methods (both bound and unbound). Extension types can easily
|
|
be made to support weak references; see section \ref{weakref-extension},
|
|
``Weak References in Extension Types,'' for more information.
|
|
|
|
|
|
\begin{funcdesc}{ref}{object\optional{, callback}}
|
|
Return a weak reference to \var{object}. If \var{callback} is
|
|
provided, it will be called when the object is about to be
|
|
finalized; the weak reference object will be passed as the only
|
|
parameter to the callback; the referent will no longer be available.
|
|
The original object can be retrieved by calling the reference
|
|
object, if the referent is still alive.
|
|
|
|
It is allowable for many weak references to be constructed for the
|
|
same object. Callbacks registered for each weak reference will be
|
|
called from the most recently registered callback to the oldest
|
|
registered callback.
|
|
|
|
Exceptions raised by the callback will be noted on the standard
|
|
error output, but cannot be propagated; they are handled in exactly
|
|
the same way as exceptions raised from an object's
|
|
\method{__del__()} method.
|
|
|
|
Weak references are hashable if the \var{object} is hashable. They
|
|
will maintain their hash value even after the \var{object} was
|
|
deleted. If \function{hash()} is called the first time only after
|
|
the \var{object} was deleted, the call will raise
|
|
\exception{TypeError}.
|
|
|
|
Weak references support test for equality, but not ordering. If the
|
|
\var{object} is still alive, to references are equal if the objects
|
|
are equal (regardless of the \var{callback}). If the \var{object}
|
|
has been deleted, they are equal iff they are identical.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{mapping}{\optional{dict\optional{, weakkeys=0}}}
|
|
Return a weak dictionary. If \var{dict} is given and not
|
|
\code{None}, the new dictionary will contain the items contained in
|
|
\var{dict}. The values from \var{dict} must be weakly referencable;
|
|
if any values which would be inserted into the new mapping are not
|
|
weakly referencable, \exception{TypeError} will be raised and the
|
|
new mapping will be empty.
|
|
|
|
If the \var{weakkeys} argument is not given or zero, the values in
|
|
the dictionary are weak. That means the entries in the dictionary
|
|
will be discarded when no strong reference to the value exists
|
|
anymore.
|
|
|
|
If the \var{weakkeys} argument is nonzero, the keys in the
|
|
dictionary are weak, i.e. the entry in the dictionary is discarded
|
|
when the last strong reference to the key is discarded.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{proxy}{object\optional{, callback}}
|
|
Return a proxy to \var{object} which uses a weak reference. This
|
|
supports use of the proxy in most contexts instead of requiring the
|
|
explicit dereferencing used with weak reference objects. The
|
|
returned object will have a type of either \code{ProxyType} or
|
|
\code{CallableProxyType}, depending on whether \var{object} is
|
|
callable. Proxy objects are not hashable regardless of the
|
|
referent; this avoids a number of problems related to their
|
|
fundamentally mutable nature, and prevent their use as dictionary
|
|
keys. \var{callable} is the same as the parameter of the same name
|
|
to the \function{ref()} function.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getweakrefcount}{object}
|
|
Return the number of weak references and proxies which refer to
|
|
\var{object}.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{getweakrefs}{object}
|
|
Return a list of all weak reference and proxy objects which refer to
|
|
\var{object}.
|
|
\end{funcdesc}
|
|
|
|
\begin{classdesc}{WeakKeyDictionary}{\optional{dict}}
|
|
The class of the mapping objects returned by \function{mapping()}
|
|
when \var{weakkeys} is true. This can be used for subclassing the
|
|
implementation if needed.
|
|
\end{classdesc}
|
|
|
|
\begin{classdesc}{WeakValueDictionary}{\optional{dict}}
|
|
The class of the mapping objects returned by \function{mapping()}
|
|
when \var{weakkeys} if false. This can be used for subclassing the
|
|
implementation if needed.
|
|
\end{classdesc}
|
|
|
|
\begin{datadesc}{ReferenceType}
|
|
The type object for weak references objects.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{ProxyType}
|
|
The type object for proxies of objects which are not callable.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{CallableProxyType}
|
|
The type object for proxies of callable objects.
|
|
\end{datadesc}
|
|
|
|
\begin{datadesc}{ProxyTypes}
|
|
Sequence containing all the type objects for proxies. This can make
|
|
it simpler to test if an object is a proxy without being dependent
|
|
on naming both proxy types.
|
|
\end{datadesc}
|
|
|
|
|
|
\begin{seealso}
|
|
\seepep{0205}{Weak References}{The proposal and rationale for this
|
|
feature, including links to earlier implementations
|
|
and information about similar features in other
|
|
languages.}
|
|
\end{seealso}
|
|
|
|
|
|
\subsection{Weak Reference Objects
|
|
\label{weakref-objects}}
|
|
|
|
Weak reference objects have no attributes or methods, but do allow the
|
|
referent to be obtained, if it still exists, by calling it:
|
|
|
|
\begin{verbatim}
|
|
>>> import weakref
|
|
>>> class Object:
|
|
... pass
|
|
...
|
|
>>> o = Object()
|
|
>>> r = weakref.ref(o)
|
|
>>> o2 = r()
|
|
>>> o is o2
|
|
1
|
|
\end{verbatim}
|
|
|
|
If the referent no longer exists, calling the reference object returns
|
|
\code{None}:
|
|
|
|
\begin{verbatim}
|
|
>>> del o, o2
|
|
>>> print r()
|
|
None
|
|
\end{verbatim}
|
|
|
|
Testing that a weak reference object is still live should be done
|
|
using the expression \code{\var{ref}.get() is not None}. Normally,
|
|
application code that needs to use a reference object should follow
|
|
this pattern:
|
|
|
|
\begin{verbatim}
|
|
o = ref.get()
|
|
if o is None:
|
|
# referent has been garbage collected
|
|
print "Object has been allocated; can't frobnicate."
|
|
else:
|
|
print "Object is still live!"
|
|
o.do_something_useful()
|
|
\end{verbatim}
|
|
|
|
Using a separate test for ``liveness'' creates race conditions in
|
|
threaded applications; another thread can cause a weak reference to
|
|
become invalidated before the \method{get()} method is called; the
|
|
idiom shown above is safe in threaded applications as well as
|
|
single-threaded applications.
|
|
|
|
|
|
\subsection{Weak References in Extension Types
|
|
\label{weakref-extension}}
|
|
|
|
One of the goals of the implementation is to allow any type to
|
|
participate in the weak reference mechanism without incurring the
|
|
overhead on those objects which do not benefit by weak referencing
|
|
(such as numbers).
|
|
|
|
For an object to be weakly referencable, the extension must include a
|
|
\ctype{PyObject *} field in the instance structure for the use of the
|
|
weak reference mechanism; it must be initialized to \NULL{} by the
|
|
object's constructor. It must also set the \member{tp_weaklistoffset}
|
|
field of the corresponding type object to the offset of the field.
|
|
For example, the instance type is defined with the following structure:
|
|
|
|
\begin{verbatim}
|
|
typedef struct {
|
|
PyObject_HEAD
|
|
PyClassObject *in_class; /* The class object */
|
|
PyObject *in_dict; /* A dictionary */
|
|
PyObject *in_weakreflist; /* List of weak references */
|
|
} PyInstanceObject;
|
|
\end{verbatim}
|
|
|
|
The statically-declared type object for instances is defined this way:
|
|
|
|
\begin{verbatim}
|
|
PyTypeObject PyInstance_Type = {
|
|
PyObject_HEAD_INIT(&PyType_Type)
|
|
0,
|
|
"instance",
|
|
|
|
/* lots of stuff omitted for brevity */
|
|
|
|
offsetof(PyInstanceObject, in_weakreflist) /* tp_weaklistoffset */
|
|
};
|
|
\end{verbatim}
|
|
|
|
The only further addition is that the destructor needs to call the
|
|
weak reference manager to clear any weak references and return if the
|
|
object has been resurrected. This needs to occur before any other
|
|
parts of the destruction have occurred:
|
|
|
|
\begin{verbatim}
|
|
static void
|
|
instance_dealloc(PyInstanceObject *inst)
|
|
{
|
|
/* allocate tempories if needed, but do not begin
|
|
destruction here
|
|
*/
|
|
|
|
if (!PyObject_ClearWeakRefs((PyObject *) inst))
|
|
return;
|
|
|
|
/* proceed with object destuction normally */
|
|
}
|
|
\end{verbatim}
|