[Python-checkins] python/dist/src/Doc/lib libweakref.tex,1.19,1.20

[tim_one at users.sourceforge.net]

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

Modified Files:
	libweakref.tex 
Log Message:
More words:  gave more motivation, and added cautions about the special
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
retrieving revision 1.20
diff -C2 -d -r1.19 -r1.20
*** libweakref.tex	2 Jul 2003 15:10:38 -0000	1.19
--- libweakref.tex	21 Nov 2003 22:20:57 -0000	1.20
***************
*** 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}