[Zodb-checkins] CVS: ZODB3/Doc/guide - prog-zodb.tex:1.3.10.2

[Tim Peters]

Update of /cvs-repository/ZODB3/Doc/guide
In directory cvs.zope.org:/tmp/cvs-serv16707/Doc/guide

Modified Files:
      Tag: Zope-2_7-branch
	prog-zodb.tex 
Log Message:
Backport doc changes about __del__ methods from ZODB 3.3.

The 3.3 docs were changed to warn against using __del__ methods in
January of 2004, but those changes weren't copied into the 3.2-line docs.


=== ZODB3/Doc/guide/prog-zodb.tex 1.3.10.1 => 1.3.10.2 ===
--- ZODB3/Doc/guide/prog-zodb.tex:1.3.10.1	Tue Sep 30 23:54:01 2003
+++ ZODB3/Doc/guide/prog-zodb.tex	Mon Mar  7 13:51:38 2005
@@ -246,6 +246,7 @@
 The summary of rules is as follows:
 
 \begin{itemize}
+
 \item If you modify a mutable object that's the value of an object's
 attribute, the ZODB can't catch that, and won't mark the object as
 dirty.  
@@ -262,9 +263,17 @@
 forth.
 
 \item Recent versions of the ZODB allow writing a class with 
-\method{__setattr__} , \method{__getattr__}, or \method{__delattr__} methods.  (Older versions didn't support this at all.)
+\method{__setattr__} , \method{__getattr__}, or \method{__delattr__} methods.
+(Older versions didn't support this at all.)
 If you write such a \method{__setattr__} or \method{__delattr__} method, 
-its code has to set the dirty bit manually, 
+its code has to set the dirty bit manually.
+
+\item A persistent class should not have a \method{__del__} method.
+The database moves objects freely between memory and storage.  If an
+object has not been used in a while, it may be released and its
+contents loaded from storage the next time it is used.  Since the
+Python interpreter is unaware of persistence, it would call
+\method{__del__} each time the object was freed.
 
 \end{itemize}
 
@@ -376,6 +385,39 @@
 method is executing.  This means that if the object is modified, the
 object should be marked as dirty by setting the object's
 \member{_p_changed} method to true.
+
+\subsubsection{\method{__del__} methods}
+
+A \method{__del__} method is invoked just before the memory occupied by an
+unreferenced Python object is freed.  Because ZODB may materialize, and
+dematerialize, a given persistent object in memory any number of times,
+there isn't a meaningful relationship between when a persistent object's
+\method{__del__} method gets invoked and any natural aspect of a
+persistent object's life cycle.  For example, it is emphatically not the
+case that a persistent object's \method{__del__} method gets invoked only
+when the object is no longer referenced by other objects in the database.
+\method{__del__} is only concerned with reachability from objects in
+memory.
+
+Worse, a \method{__del__} method can interfere with the persistence
+machinery's goals.  For example, some number of persistent objects reside
+in a \class{Connection}'s memory cache.  At various times, to reduce memory
+burden, objects that haven't been referenced recently are removed from the
+cache.  If a persistent object with a \method{__del___} method is so
+removed, and the cache was holding the last memory reference to the object,
+the object's \method{__del__} method will be invoked.  If the
+\method{__del__} method then references any attribute of the object, ZODB
+needs to load the object from the database again, in order to satisfy the
+attribute reference.  This puts the object back into the cache again:  such
+an object is effectively immortal, occupying space in the memory cache
+forever, as every attempt to remove it from cache puts it back into the
+cache.  In ZODB versions prior to 3.2.2, this could even cause the cache
+reduction code to fall into an infinite loop.  The infinite loop no longer
+occurs, but such objects continue to live in the memory cache forever.
+
+Because \method{__del__} methods don't make good sense for persistent
+objects, and can create problems, persistent classes should not define
+\method{__del__} methods.
 
 \subsection{Writing Persistent Classes}