[Zodb-checkins]
SVN: ZODB/branches/anguenot-ordering-beforecommitsubscribers/src/transaction/
Repair commit hook interfaces to reflect changes in
Tim Peters
tim.one at comcast.net
Fri Aug 12 18:27:18 EDT 2005
Log message for revision 37901:
Repair commit hook interfaces to reflect changes in
method names and signatures. Note that
getBeforeCommitHooks() no longer promises (nor should it)
to return hook info in registration order.
Fiddled assorted comments.
Changed:
U ZODB/branches/anguenot-ordering-beforecommitsubscribers/src/transaction/_transaction.py
U ZODB/branches/anguenot-ordering-beforecommitsubscribers/src/transaction/interfaces.py
-=-
Modified: ZODB/branches/anguenot-ordering-beforecommitsubscribers/src/transaction/_transaction.py
===================================================================
--- ZODB/branches/anguenot-ordering-beforecommitsubscribers/src/transaction/_transaction.py 2005-08-12 21:47:52 UTC (rev 37900)
+++ ZODB/branches/anguenot-ordering-beforecommitsubscribers/src/transaction/_transaction.py 2005-08-12 22:27:18 UTC (rev 37901)
@@ -239,10 +239,14 @@
# raised, incorporating this traceback.
self._failure_traceback = None
- # Holds (order, index, hook, args, kws) added by
- # addbeforeCommitHook. TODO: in Python 2.4, change to
- # collections.deque; lists can be inefficient for FIFO access
- # of this kind.
+ # List of (order, index, hook, args, kws) tuples added by
+ # addbeforeCommitHook(). `index` is used to resolve ties on equal
+ # `order` values, preserving the order in which the hooks were
+ # registered. Each time we append a tuple to _before_commit,
+ # the current value of _before_commit_index is used for the
+ # index, and then the latter is incremented by 1.
+ # TODO: in Python 2.4, change to collections.deque; lists can be
+ # inefficient for FIFO access of this kind.
self._before_commit = []
self._before_commit_index = 0
@@ -412,25 +416,21 @@
def getBeforeCommitHooks(self):
# Don't return the hook order and index values because of
- # backward compatibility. As well, those are internals
- return iter([x[2:5] for x in self._before_commit])
-
+ # backward compatibility, and because they're internal details.
+ return iter([x[2:] for x in self._before_commit])
+
def addBeforeCommitHook(self, hook, args=(), kws=None, order=0):
if not isinstance(order, int):
raise ValueError("An integer value is required "
"for the order argument")
if kws is None:
kws = {}
- # `index` goes up by 1 on each append. Then no two tuples can
- # compare equal, and indeed no more than the `order` and
- # `index` fields ever get compared when the tuples are compared
- # (because no two `index` fields are equal).
bisect.insort(self._before_commit, (order, self._before_commit_index,
hook, tuple(args), kws))
self._before_commit_index += 1
def beforeCommitHook(self, hook, *args, **kws):
- # Default order is zero (0)
+ # Default order is zero.
self.addBeforeCommitHook(hook, args, kws, order=0)
def _callBeforeCommitHooks(self):
Modified: ZODB/branches/anguenot-ordering-beforecommitsubscribers/src/transaction/interfaces.py
===================================================================
--- ZODB/branches/anguenot-ordering-beforecommitsubscribers/src/transaction/interfaces.py 2005-08-12 21:47:52 UTC (rev 37900)
+++ ZODB/branches/anguenot-ordering-beforecommitsubscribers/src/transaction/interfaces.py 2005-08-12 22:27:18 UTC (rev 37901)
@@ -170,6 +170,8 @@
def beforeCommitHook(__hook, *args, **kws):
"""Register a hook to call before the transaction is committed.
+ THIS IS DEPRECATED IN ZODB 3.5. Use addBeforeCommitHook() instead.
+
The specified hook function will be called after the transaction's
commit method has been called, but before the commit process has been
started. The hook will be passed the specified positional and keyword
@@ -192,47 +194,51 @@
instead.
"""
- def beforeCommitHookOrdered(__hook, __order, *args, **kws):
+ def addBeforeCommitHook(hook, args=(), kws=None, order=0):
"""Register a hook to call before the transaction is committed.
The specified hook function will be called after the transaction's
commit method has been called, but before the commit process has been
- started. The hook will be passed the specified positional and keyword
- arguments.
+ started. The hook will be passed the specified positional (`args`)
+ and keyword (`kws`) arguments. `args` is a sequence of positional
+ arguments to be passed, defaulting to an empty tuple (no positional
+ arguments are passed). `kws` is a dictionary of keyword argument
+ names and values to be passed, or the default None (no keyword
+ arguments are passed).
Multiple hooks can be registered and will be called in the order they
- were registered (first registered, first called) unless they
- explicitly provide an argument named 'order' that will be used to
- define the order in which the hooks will be invoked.
+ were registered (first registered, first called), except that
+ hooks registered with different `order` arguments are invoked from
+ smallest `order` value to largest. `order` must be an integer,
+ and defaults to 0.
- For instance, a hook registered with an order=1 will be invoked after
- another hook registred within an order=-999999 and before another one
- registred with an order=999999. If two hooks are registred with the
- same order then those will be called in the order the were registred.
+ For instance, a hook registered with order=1 will be invoked after
+ another hook registered with order=-1 and before another registered
+ with order=2, regardless of which was registered first. When two
+ hooks are registered with the same order, the first one registered is
+ called first.
- Note, a hook __call__() method can't define any 'order' argument since
- this one is reserved by this method
-
This method can also be called from a hook: an executing hook can
register more hooks. Applications should take care to avoid creating
infinite loops by recursively registering hooks.
Hooks are called only for a top-level commit. A subtransaction
- commit does not call any hooks. If the transaction is aborted, hooks
- are not called, and are discarded. Calling a hook "consumes" its
- registration too: hook registrations do not persist across
- transactions. If it's desired to call the same hook on every
- transaction commit, then beforeCommitHook() must be called with that
- hook during every transaction; in such a case consider registering a
- synchronizer object via a TransactionManager's registerSynch() method
- instead.
+ commit or savepoint creation does not call any hooks. If the
+ transaction is aborted, hooks are not called, and are discarded.
+ Calling a hook "consumes" its registration too: hook registrations
+ do not persist across transactions. If it's desired to call the same
+ hook on every transaction commit, then addBeforeCommitHook() must be
+ called with that hook during every transaction; in such a case
+ consider registering a synchronizer object via a TransactionManager's
+ registerSynch() method instead.
"""
def getBeforeCommitHooks():
- """Return iterable producing the registered beforeCommit hooks.
+ """Return iterable producing the registered addBeforeCommit hooks.
A triple (hook, args, kws) is produced for each registered hook.
- The hooks are produced in the order in which they were registered.
+ The hooks are produced in the order in which they would be invoked
+ by a top-level transaction commit.
"""
class ITransactionDeprecated(zope.interface.Interface):
More information about the Zodb-checkins
mailing list