[Zodb-checkins] SVN: ZODB/trunk/doc/guide/modules.tex Added long-requested docs about mutating BTrees while iterating over them. Will regen the .pdf and .html later (I want to add more .tex docs first).

Tim Peters tim.one at comcast.net
Fri May 14 16:20:32 EDT 2004


Log message for revision 24687:
Added long-requested docs about mutating BTrees while iterating over them.  Will regen the .pdf and .html later (I want to add more .tex docs first).


-=-
Modified: ZODB/trunk/doc/guide/modules.tex
===================================================================
--- ZODB/trunk/doc/guide/modules.tex	2004-05-14 20:16:50 UTC (rev 24686)
+++ ZODB/trunk/doc/guide/modules.tex	2004-05-14 20:20:31 UTC (rev 24687)
@@ -3,6 +3,7 @@
 %    PersistentList
 %    BTrees
 %       Total Ordering and Persistence
+%       Iteration and Mutation
 %       BTree Diagnostic Tools
 
 \section{Related Modules}
@@ -362,6 +363,51 @@
 \end{enumerate}
 
 
+\subsubsection{Iteration and Mutation}
+
+As with a Python dictionary or list, you should not mutate a BTree-based
+data structure while iterating over it, except that it's fine to replace
+the value associated with an existing key while iterating.  You won't
+create internal damage in the structure if you try to remove, or add new
+keys, while iterating, but the results are undefined and unpredictable.  A
+weak attempt is made to raise \exception{RuntimeError} if the size of a
+BTree-based structure changes while iterating, but it doesn't catch most
+such cases, and is also unreliable.  Example:
+
+\begin{verbatim}
+    >>> from BTrees.IIBTree import *
+    >>> s = IISet(range(10))
+    >>> list(s)
+    [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
+    >>> for i in s:  # the output is undefined
+    ...     print i,
+    ...     s.remove(i)
+    0 2 4 6 8
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in ?
+    RuntimeError: the bucket being iterated changed size
+    >>> list(s)      # this output is also undefined
+    [1, 3, 5, 7, 9]
+    >>>
+\end{verbatim}
+
+Also as with Python dictionaries and lists, the safe and predictable way
+to mutate a BTree-based structure while iterating over it is to iterate
+over a copy of the keys.  Example:
+
+\begin{verbatim}
+    >>> from BTrees.IIBTree import *
+    >>> s = IISet(range(10))
+    >>> for i in list(s.keys()):  # this is well defined
+    ...     print i,
+    ...     s.remove(i)
+    0 1 2 3 4 5 6 7 8 9
+    >>> list(s)
+    []
+    >>>
+\end{verbatim}
+
+
 \subsubsection{BTree Diagnostic Tools}
 
 A BTree (or TreeSet) is a complex data structure, really a graph of




More information about the Zodb-checkins mailing list