# [Python-checkins] python/dist/src/Doc/lib libweakref.tex, 1.19.8.1, 1.19.8.2

tim_one at users.sourceforge.net tim_one at users.sourceforge.net
Fri Nov 21 17:21:21 EST 2003

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv29116/Doc/lib

Modified Files:
Tag: release23-maint
libweakref.tex
Log Message:
dangers of trying to iterate over weak dicts.

Index: libweakref.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libweakref.tex,v
retrieving revision 1.19.8.1
retrieving revision 1.19.8.2
diff -C2 -d -r1.19.8.1 -r1.19.8.2
*** libweakref.tex	7 Sep 2003 23:38:08 -0000	1.19.8.1
--- libweakref.tex	21 Nov 2003 22:21:19 -0000	1.19.8.2
***************
*** 15,22 ****
\dfn{weak references} to objects.

! In the discussion which follows, the term \dfn{referent} means the
object which is referred to by a weak reference.

! XXX --- need to say more here!

Not all objects can be weakly referenced; those objects which can
--- 15,49 ----
\dfn{weak references} to objects.

! In the following, the term \dfn{referent} means the
object which is referred to by a weak reference.

! A weak reference to an object is not enough to keep the object alive:
! when the only remaining references to a referent are weak references,
! garbage collection is free to destroy the referent and reuse its memory
! for something else.  A primary use for weak references is to implement
! caches or mappings holding large objects, where it's desired that a
! large object not be kept alive solely because it appears in a cache or
! mapping.  For example, if you have a number of large binary image objects,
! you may wish to associate a name with each.  If you used a Python
! dictionary to map names to images, or images to names, the image objects
! would remain alive just because they appeared as values or keys in the
! dictionaries.  The \class{WeakKeyDictionary} and
! \class{WeakValueDictionary} classes supplied by the \module{weakref}
! module are an alternative, using weak references to construct mappings
! that don't keep objects alive solely because they appear in the mapping
! objects.  If, for example, an image object is a value in a
! \class{WeakValueDictionary}, then when the last remaining
! references to that image object are the weak references held by weak
! mappings, garbage collection can reclaim the object, and its corresponding
! entries in weak mappings are simply deleted.
!
! \class{WeakKeyDictionary} and \class{WeakValueDictionary} use weak
! references in their implementation, setting up callback functions on
! the weak references that notify the weak dictionaries when a key or value
! has been reclaimed by garbage collection.  Most programs should find that
! using one of these weak dictionary types is all they need -- it's
! not usually necessary to create your own weak references directly.  The
! low-level machinery used by the weak dictionary implementations is exposed
! by the \module{weakref} module for the benefit of advanced uses.

Not all objects can be weakly referenced; those objects which can
***************
*** 45,49 ****
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
--- 72,76 ----
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
***************
*** 51,55 ****
the \var{object} was deleted, the call will raise
\exception{TypeError}.
!
Weak references support tests for equality, but not ordering.  If
the referents are still alive, two references have the same
--- 78,82 ----
the \var{object} was deleted, the call will raise
\exception{TypeError}.
!
Weak references support tests for equality, but not ordering.  If
the referents are still alive, two references have the same
***************
*** 90,93 ****
--- 117,127 ----
attributes to those objects.  This can be especially useful with
objects that override attribute accesses.
+
+   \note{Caution:  Because a \class{WeakKeyDictionary} is built on top
+         of a Python dictionary, it must not change size when iterating
+         over it.  This can be difficult to ensure for a
+         \class{WeakKeyDictionary} because actions performed by the
+         program during iteration may cause items in the dictionary
+         to vanish "by magic" (as a side effect of garbage collection).}
\end{classdesc}

***************
*** 96,99 ****
--- 130,140 ----
dictionary will be discarded when no strong reference to the value
exists any more.
+
+   \note{Caution:  Because a \class{WeakValueDictionary} is built on top
+         of a Python dictionary, it must not change size when iterating
+         over it.  This can be difficult to ensure for a
+         \class{WeakValueDictionary} because actions performed by the
+         program during iteration may cause items in the dictionary
+         to vanish "by magic" (as a side effect of garbage collection).}
\end{classdesc}

***************
*** 254,265 ****

\begin{verbatim}
! static PyObject *
! instance_new() {
!     /* Other initialization stuff omitted for brevity */

!     self->in_weakreflist = NULL;

!     return (PyObject *) self;
! }
\end{verbatim}

--- 295,306 ----

\begin{verbatim}
! static PyObject *
! instance_new() {
!     /* Other initialization stuff omitted for brevity */

!     self->in_weakreflist = NULL;

!     return (PyObject *) self;
! }
\end{verbatim}