[Python-checkins] CVS: python/dist/src/Doc/lib libweakref.tex,1.14,1.15

[Fred L. Drake]

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

Modified Files:
	libweakref.tex 
Log Message:
Many, many small fixes and improvements, most suggested by Detlef Lannert.

Index: libweakref.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libweakref.tex,v
retrieving revision 1.14
retrieving revision 1.15
diff -C2 -d -r1.14 -r1.15
*** libweakref.tex	2001/10/26 11:27:54	1.14
--- libweakref.tex	2001/10/26 17:40:22	1.15
***************
*** 15,18 ****
--- 15,21 ----
  \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!
  
***************
*** 25,34 ****
  
  \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
--- 28,38 ----
  
  \begin{funcdesc}{ref}{object\optional{, callback}}
!   Return a weak reference to \var{object}.  The original object can be
!   retrieved by calling the reference object if the referent is still
!   alive; if the referent is no longer alive, calling the reference
!   object will cause \code{None} to be returned.  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.
  
    It is allowable for many weak references to be constructed for the
***************
*** 49,56 ****
    
    Weak references support tests for equality, but not ordering.  If
!   the \var{object} is still alive, two references are equal if the
!   objects are equal (regardless of the \var{callback}).  If
!   \var{object} has been deleted, they are equal only if the references
!   being compared are the same reference object.
  \end{funcdesc}
  
--- 53,61 ----
    
    Weak references support tests for equality, but not ordering.  If
!   the referents are still alive, two references have the same
!   equalality relationship as their referents (regardless of the
!   \var{callback}).  If either referent has been deleted, the
!   references are equal only if the reference objects are the same
!   object.
  \end{funcdesc}
  
***************
*** 90,94 ****
    Mapping class that references values weakly.  Entries in the
    dictionary will be discarded when no strong reference to the value
!   exists anymore.
  \end{classdesc}
  
--- 95,99 ----
    Mapping class that references values weakly.  Entries in the
    dictionary will be discarded when no strong reference to the value
!   exists any more.
  \end{classdesc}
  
***************
*** 159,163 ****
  
  \begin{verbatim}
! o = ref()
  if o is None:
      # referent has been garbage collected
--- 164,169 ----
  
  \begin{verbatim}
! # r is a weak reference object
! o = r()
  if o is None:
      # referent has been garbage collected
***************
*** 170,174 ****
  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.
--- 176,180 ----
  Using a separate test for ``liveness'' creates race conditions in
  threaded applications; another thread can cause a weak reference to
! become invalidated before the weak reference is called; the
  idiom shown above is safe in threaded applications as well as
  single-threaded applications.
***************
*** 190,197 ****
  
  def remember(obj):
!     _id2obj_dict[id(obj)] = obj
  
! def id2obj(id):
!     return _id2obj_dict(id)
  \end{verbatim}
  
--- 196,205 ----
  
  def remember(obj):
!     oid = id(obj)
!     _id2obj_dict[oid] = obj
!     return oid
  
! def id2obj(oid):
!     return _id2obj_dict[oid]
  \end{verbatim}
  
***************
*** 206,210 ****
  
  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}
--- 214,218 ----
  
  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}
***************
*** 237,241 ****
  The only further addition is that the destructor needs to call the
  weak reference manager to clear any weak references.  This should be
! done before any other parts of the destruction have occurred:
  
  \begin{verbatim}
--- 245,250 ----
  The only further addition is that the destructor needs to call the
  weak reference manager to clear any weak references.  This should be
! done before any other parts of the destruction have occurred, but is
! only required if the weak reference list is non-\NULL:
  
  \begin{verbatim}
***************
*** 243,251 ****
  instance_dealloc(PyInstanceObject *inst)
  {
!     /* Allocate tempories if needed, but do not begin
         destruction just yet.
       */
  
!     PyObject_ClearWeakRefs((PyObject *) inst);
  
      /* Proceed with object destruction normally. */
--- 252,261 ----
  instance_dealloc(PyInstanceObject *inst)
  {
!     /* Allocate temporaries if needed, but do not begin
         destruction just yet.
       */
  
!     if (inst->in_weakreflist != NULL)
!         PyObject_ClearWeakRefs((PyObject *) inst);
  
      /* Proceed with object destruction normally. */