Doc/lib/libweakref.tex

   1 \section{\module{weakref} ---
   2          Weak references}
   3
   4 \declaremodule{extension}{weakref}
   5 \modulesynopsis{Support for weak references and weak dictionaries.}
   6 \moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
   7 \moduleauthor{Neil Schemenauer}{nas@arctrix.com}
   8 \moduleauthor{Martin von L\"owis}{martin@loewis.home.cs.tu-berlin.de}
   9 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
  10
  11 \versionadded{2.1}
  12
  13
  14 The \module{weakref} module allows the Python programmer to create
  15 \dfn{weak references} to objects.
  16
  17 XXX --- need to say more here!
  18
  19 Not all objects can be weakly referenced; those objects which do
  20 include class instances, functions written in Python (but not in C),
  21 and methods (both bound and unbound).  Extension types can easily
  22 be made to support weak references; see section \ref{weakref-extension},
  23 ``Weak References in Extension Types,'' for more information.
  24
  25
  26 \begin{funcdesc}{ref}{object\optional{, callback}}
  27   Return a weak reference to \var{object}.  If \var{callback} is
  28   provided, it will be called when the object is about to be
  29   finalized; the weak reference object will be passed as the only
  30   parameter to the callback; the referent will no longer be available.
  31   The original object can be retrieved by calling the reference
  32   object, if the referent is still alive.
  33
  34   It is allowable for many weak references to be constructed for the
  35   same object.  Callbacks registered for each weak reference will be
  36   called from the most recently registered callback to the oldest
  37   registered callback.
  38
  39   Exceptions raised by the callback will be noted on the standard
  40   error output, but cannot be propagated; they are handled in exactly
  41   the same way as exceptions raised from an object's
  42   \method{__del__()} method.
  43
  44   Weak references are hashable if the \var{object} is hashable.  They
  45   will maintain their hash value even after the \var{object} was
  46   deleted.  If \function{hash()} is called the first time only after
  47   the \var{object} was deleted, the call will raise
  48   \exception{TypeError}.
  49
  50   Weak references support test for equality, but not ordering.  If the
  51   \var{object} is still alive, to references are equal if the objects
  52   are equal (regardless of the \var{callback}).  If the \var{object}
  53   has been deleted, they are equal iff they are identical.
  54 \end{funcdesc}
  55
  56 \begin{funcdesc}{proxy}{object\optional{, callback}}
  57   Return a proxy to \var{object} which uses a weak reference.  This
  58   supports use of the proxy in most contexts instead of requiring the
  59   explicit dereferencing used with weak reference objects.  The
  60   returned object will have a type of either \code{ProxyType} or
  61   \code{CallableProxyType}, depending on whether \var{object} is
  62   callable.  Proxy objects are not hashable regardless of the
  63   referent; this avoids a number of problems related to their
  64   fundamentally mutable nature, and prevent their use as dictionary
  65   keys.  \var{callback} is the same as the parameter of the same name
  66   to the \function{ref()} function.
  67 \end{funcdesc}
  68
  69 \begin{funcdesc}{getweakrefcount}{object}
  70   Return the number of weak references and proxies which refer to
  71   \var{object}.
  72 \end{funcdesc}
  73
  74 \begin{funcdesc}{getweakrefs}{object}
  75   Return a list of all weak reference and proxy objects which refer to
  76   \var{object}.
  77 \end{funcdesc}
  78
  79 \begin{classdesc}{WeakKeyDictionary}{\optional{dict}}
  80   Mapping class that references keys weakly.  Entries in the
  81   dictionary will be discarded when there is no longer a strong
  82   reference to the key.  This can be used to associate additional data
  83   with an object owned by other parts of an application without adding
  84   attributes to those objects.  This can be especially useful with
  85   objects that override attribute accesses.
  86 \end{classdesc}
  87
  88 \begin{classdesc}{WeakValueDictionary}{\optional{dict}}
  89   Mapping class that references values weakly.  Entries in the
  90   dictionary will be discarded when no strong reference to the value
  91   exists anymore.
  92 \end{classdesc}
  93
  94 \begin{datadesc}{ReferenceType}
  95   The type object for weak references objects.
  96 \end{datadesc}
  97
  98 \begin{datadesc}{ProxyType}
  99   The type object for proxies of objects which are not callable.
 100 \end{datadesc}
 101
 102 \begin{datadesc}{CallableProxyType}
 103   The type object for proxies of callable objects.
 104 \end{datadesc}
 105
 106 \begin{datadesc}{ProxyTypes}
 107   Sequence containing all the type objects for proxies.  This can make
 108   it simpler to test if an object is a proxy without being dependent
 109   on naming both proxy types.
 110 \end{datadesc}
 111
 112 \begin{excdesc}{ReferenceError}
 113   Exception raised when a proxy object is used but the underlying
 114   object has been collected.
 115 \end{excdesc}
 116
 117
 118 \begin{seealso}
 119   \seepep{0205}{Weak References}{The proposal and rationale for this
 120                 feature, including links to earlier implementations
 121                 and information about similar features in other
 122                 languages.}
 123 \end{seealso}
 124
 125
 126 \subsection{Weak Reference Objects
 127             \label{weakref-objects}}
 128
 129 Weak reference objects have no attributes or methods, but do allow the
 130 referent to be obtained, if it still exists, by calling it:
 131
 132 \begin{verbatim}
 133 >>> import weakref
 134 >>> class Object:
 135 ...     pass
 136 ...
 137 >>> o = Object()
 138 >>> r = weakref.ref(o)
 139 >>> o2 = r()
 140 >>> o is o2
 141 1
 142 \end{verbatim}
 143
 144 If the referent no longer exists, calling the reference object returns
 145 \code{None}:
 146
 147 \begin{verbatim}
 148 >>> del o, o2
 149 >>> print r()
 150 None
 151 \end{verbatim}
 152
 153 Testing that a weak reference object is still live should be done
 154 using the expression \code{\var{ref}.get() is not None}.  Normally,
 155 application code that needs to use a reference object should follow
 156 this pattern:
 157
 158 \begin{verbatim}
 159 o = ref.get()
 160 if o is None:
 161     # referent has been garbage collected
 162     print "Object has been allocated; can't frobnicate."
 163 else:
 164     print "Object is still live!"
 165     o.do_something_useful()
 166 \end{verbatim}
 167
 168 Using a separate test for ``liveness'' creates race conditions in
 169 threaded applications; another thread can cause a weak reference to
 170 become invalidated before the \method{get()} method is called; the
 171 idiom shown above is safe in threaded applications as well as
 172 single-threaded applications.
 173
 174
 175 \subsection{Example \label{weakref-example}}
 176
 177 This simple example shows how an application can use objects IDs to
 178 retrieve objects that it has seen before.  The IDs of the objects can
 179 then be used in other data structures without forcing the objects to
 180 remain alive, but the objects can still be retrieved by ID if they
 181 do.
 182
 183 % Example contributed by Tim Peters <tim_one@msn.com>.
 184 \begin{verbatim}
 185 import weakref
 186
 187 _id2obj_dict = weakref.WeakValueDictionary()
 188
 189 def remember(obj):
 190     _id2obj_dict[id(obj)] = obj
 191
 192 def id2obj(id):
 193     return _id2obj_dict.get(id)
 194 \end{verbatim}
 195
 196
 197 \subsection{Weak References in Extension Types
 198             \label{weakref-extension}}
 199
 200 One of the goals of the implementation is to allow any type to
 201 participate in the weak reference mechanism without incurring the
 202 overhead on those objects which do not benefit by weak referencing
 203 (such as numbers).
 204
 205 For an object to be weakly referencable, the extension must include a
 206 \ctype{PyObject *} field in the instance structure for the use of the
 207 weak reference mechanism; it must be initialized to \NULL{} by the
 208 object's constructor.  It must also set the \member{tp_weaklistoffset}
 209 field of the corresponding type object to the offset of the field.
 210 For example, the instance type is defined with the following structure:
 211
 212 \begin{verbatim}
 213 typedef struct {
 214     PyObject_HEAD
 215     PyClassObject *in_class;       /* The class object */
 216     PyObject      *in_dict;        /* A dictionary */
 217     PyObject      *in_weakreflist; /* List of weak references */
 218 } PyInstanceObject;
 219 \end{verbatim}
 220
 221 The statically-declared type object for instances is defined this way:
 222
 223 \begin{verbatim}
 224 PyTypeObject PyInstance_Type = {
 225     PyObject_HEAD_INIT(&PyType_Type)
 226     0,
 227     "instance",
 228
 229     /* Lots of stuff omitted for brevity... */
 230
 231     offsetof(PyInstanceObject, in_weakreflist) /* tp_weaklistoffset */
 232 };
 233 \end{verbatim}
 234
 235 The only further addition is that the destructor needs to call the
 236 weak reference manager to clear any weak references.  This should be
 237 done before any other parts of the destruction have occurred:
 238
 239 \begin{verbatim}
 240 static void
 241 instance_dealloc(PyInstanceObject *inst)
 242 {
 243     /* Allocate tempories if needed, but do not begin
 244        destruction just yet.
 245      */
 246
 247     PyObject_ClearWeakRefs((PyObject *) inst);
 248
 249     /* Proceed with object destuction normally. */
 250 }
 251 \end{verbatim}