[Zope3-checkins] CVS: Zope3/src/transaction - _transaction.py:1.1.2.30

[Jeremy Hylton]

Update of /cvs-repository/Zope3/src/transaction
In directory cvs.zope.org:/tmp/cvs-serv7666/src/transaction

Modified Files:
      Tag: jeremy-txn-branch
	_transaction.py 
Log Message:
Flesh out description of two-phase commit.
Remove BasicResourceAdapter and fold its contents into lone subclass.


=== Zope3/src/transaction/_transaction.py 1.1.2.29 => 1.1.2.30 ===
--- Zope3/src/transaction/_transaction.py:1.1.2.29	Mon Mar 29 23:32:56 2004
+++ Zope3/src/transaction/_transaction.py	Tue Mar 30 12:15:04 2004
@@ -74,12 +74,49 @@
 Two-phase commit
 ----------------
 
-Brief description of two-phase commit goes here.
+A transaction commit involves an interaction between the transaction
+object and one or more resource managers.  The transaction manager
+calls the following four methods on each resource manager; it calls
+tpc_begin() on each resource manager before calling commit() on any of
+them.
+
+    1. tpc_begin()
+    2. commit()
+    3. tpc_vote()
+    4. tpc_finish()
+
+Subtransaction commit
+---------------------
+
+When a subtransaction commits, the protocol is different.
+
+1. tpc_begin() is passed a second argument, which indicates that a
+   subtransaction is begin committed.
+2. tpc_vote() is not called.
+
+Once a subtransaction has been committed, the top-level transaction
+commit will start with a commit_sub() called instead of a tpc_begin()
+call.
 
 Error handling
 --------------
 
-When errors occur during two-phase commit, ...
+When errors occur during two-phase commit, the transaction manager
+aborts all the resource managers.  The specific methods it calls
+depend on whether the error occurs before or after the call to
+tpc_vote() on that transaction manager.
+
+If the resource manager has not voted, then the resource manager will
+have one or more uncommitted objects.  There are two cases that lead
+to this state; either the transaction manager has not called commit()
+for any objects on this resource manager or the call that failed was a
+commit() for one of the objects of this resource manager.  For each
+uncommitted object, including the object that failed in its commit(),
+call abort().
+
+Once uncommitted objects are aborted, tpc_abort() or abort_sub() is
+called on each resource manager.  abort_sub() is called if the
+resource manager was involved in a subtransaction.
 """
 
 import logging
@@ -248,7 +285,7 @@
     def _cleanup(self, L):
         # Called when an exception occurs during tpc_vote or tpc_finish.
         for rm in L:
-            if id(rm) in self._voted:
+            if id(rm) not in self._voted:
                 rm.cleanup(self)
         for rm in L:
             if id(rm) in self._sub:
@@ -352,9 +389,18 @@
 
 # XXX We need a better name for the adapters.
 
-class BasicResourceAdapter(object):
+class MultiObjectResourceAdapter(object):
+    """Adapt the old-style register() call to the new-style join().
 
-    # subclass must define an __init__ that binds self.manager
+    With join(), a resource mananger like a Connection registers with
+    the transaction manager.  With register(), an individual object
+    is passed to register().
+    """
+
+    def __init__(self, jar):
+        self.manager = jar
+        self.objects = []
+        self.ncommitted = 0
 
     def __repr__(self):
         return "<%s for %s at %s>" % (self.__class__.__name__,
@@ -372,19 +418,6 @@
     def tpc_abort(self, txn):
         self.manager.tpc_abort(txn)
 
-
-class MultiObjectResourceAdapter(BasicResourceAdapter):
-    """Adapt the old-style register() call to the new-style join().
-
-    With join(), a resource mananger like a Connection registers with
-    the transaction manager.  With register(), an individual object
-    is passed to register().
-    """
-
-    def __init__(self, jar):
-        self.manager = jar
-        self.objects = []
-        self.ncommitted = 0
 
     def commit(self, txn):
         for o in self.objects: