From 7901868a60624d501ac581451459e2e068ce6fb8 Mon Sep 17 00:00:00 2001 From: Jim Fulton Date: Thu, 30 Jun 2016 16:55:41 -0400 Subject: [PATCH 1/5] Define a new interface for storages that support the new commit protocol. This allows interface incompatibilities: - Future version of ZODB that requires the new protocol being configured with a storage that doesn't implement the new protocol - ZEO has a client that uses the old protocol can't use a storage that implements the new protocol. To be caught early. This commit also clarifies that the serial returned by ``undo()`` is ignored. --- src/ZODB/interfaces.py | 90 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 88 insertions(+), 2 deletions(-) diff --git a/src/ZODB/interfaces.py b/src/ZODB/interfaces.py index 716cb0f99..7f6364af7 100644 --- a/src/ZODB/interfaces.py +++ b/src/ZODB/interfaces.py @@ -811,6 +811,92 @@ def tpc_vote(transaction): either from tpc_vote or store for objects passed to store. """ +class IMultiCommitStorage(IStorage): + """A multi-commit storage can commit multiple transactions at once. + + It's lilely that future versions of ZODB will require all storages + to provide this interface. + """ + + def store(oid, serial, data, version, transaction): + """Store data for the object id, oid. + + Arguments: + + oid + The object identifier. This is either a string + consisting of 8 nulls or a string previously returned by + new_oid. + + serial + The serial of the data that was read when the object was + loaded from the database. If the object was created in + the current transaction this will be a string consisting + of 8 nulls. + + data + The data record. This is opaque to the storage. + + version + This must be an empty string. It exists for backward compatibility. + + transaction + A transaction object. This should match the current + transaction for the storage, set by tpc_begin. + + None is returned. + + Several different exceptions may be raised when an error occurs. + + ConflictError + is raised when serial does not match the most recent serial + number for object oid and the conflict was not resolved by + the storage. + + StorageTransactionError + is raised when transaction does not match the current + transaction. + + StorageError or, more often, a subclass of it + is raised when an internal error occurs while the storage is + handling the store() call. + + """ + + def tpc_finish(transaction, func = lambda tid: None): + """Finish the transaction, making any transaction changes permanent. + + Changes must be made permanent at this point. + + This call raises a StorageTransactionError if the storage + isn't participating in two-phase commit. Failure of this + method is extremely serious. + + The second argument is a call-back function that must be + called while the storage transaction lock is held. It takes + the new transaction id generated by the transaction. + + The return value must be the committed tid. It is used to set the + serial for objects whose ids were passed to previous store calls + in the same transaction. + """ + + def tpc_vote(transaction): + """Provide a storage with an opportunity to veto a transaction + + This call raises a StorageTransactionError if the storage + isn't participating in two-phase commit or if it is commiting + a different transaction. + + If a transaction can be committed by a storage, then the + method should return. If a transaction cannot be committed, + then an exception should be raised. If this method returns + without an error, then there must not be an error if + tpc_finish or tpc_abort is called subsequently. + + The return value can be either None or a sequence of oids for which + a conflict was resolved. + """ class IStorageRestoreable(IStorage): """Copying Transactions @@ -948,8 +1034,8 @@ def undo(transaction_id, transaction): This method must only be called in the first phase of two-phase commit (after tpc_begin but before tpc_vote). It returns a serial (transaction id) and a sequence of object ids - for objects affected by the transaction. - + for objects affected by the transaction. The serial is ignored + and may be None. """ # Used by DB (Actually, by TransactionalUndo) From c5fe46d041e82d546532b1779128631ed3c48cc6 Mon Sep 17 00:00:00 2001 From: Jim Fulton Date: Thu, 30 Jun 2016 16:58:56 -0400 Subject: [PATCH 2/5] Revert "Define a new interface for storages that support the new commit protocol." This reverts commit 7901868a60624d501ac581451459e2e068ce6fb8. --- src/ZODB/interfaces.py | 90 +----------------------------------------- 1 file changed, 2 insertions(+), 88 deletions(-) diff --git a/src/ZODB/interfaces.py b/src/ZODB/interfaces.py index 7f6364af7..716cb0f99 100644 --- a/src/ZODB/interfaces.py +++ b/src/ZODB/interfaces.py @@ -811,92 +811,6 @@ def tpc_vote(transaction): either from tpc_vote or store for objects passed to store. """ -class IMultiCommitStorage(IStorage): - """A multi-commit storage can commit multiple transactions at once. - - It's lilely that future versions of ZODB will require all storages - to provide this interface. - """ - - def store(oid, serial, data, version, transaction): - """Store data for the object id, oid. - - Arguments: - - oid - The object identifier. This is either a string - consisting of 8 nulls or a string previously returned by - new_oid. - - serial - The serial of the data that was read when the object was - loaded from the database. If the object was created in - the current transaction this will be a string consisting - of 8 nulls. - - data - The data record. This is opaque to the storage. - - version - This must be an empty string. It exists for backward compatibility. - - transaction - A transaction object. This should match the current - transaction for the storage, set by tpc_begin. - - None is returned. - - Several different exceptions may be raised when an error occurs. - - ConflictError - is raised when serial does not match the most recent serial - number for object oid and the conflict was not resolved by - the storage. - - StorageTransactionError - is raised when transaction does not match the current - transaction. - - StorageError or, more often, a subclass of it - is raised when an internal error occurs while the storage is - handling the store() call. - - """ - - def tpc_finish(transaction, func = lambda tid: None): - """Finish the transaction, making any transaction changes permanent. - - Changes must be made permanent at this point. - - This call raises a StorageTransactionError if the storage - isn't participating in two-phase commit. Failure of this - method is extremely serious. - - The second argument is a call-back function that must be - called while the storage transaction lock is held. It takes - the new transaction id generated by the transaction. - - The return value must be the committed tid. It is used to set the - serial for objects whose ids were passed to previous store calls - in the same transaction. - """ - - def tpc_vote(transaction): - """Provide a storage with an opportunity to veto a transaction - - This call raises a StorageTransactionError if the storage - isn't participating in two-phase commit or if it is commiting - a different transaction. - - If a transaction can be committed by a storage, then the - method should return. If a transaction cannot be committed, - then an exception should be raised. If this method returns - without an error, then there must not be an error if - tpc_finish or tpc_abort is called subsequently. - - The return value can be either None or a sequence of oids for which - a conflict was resolved. - """ class IStorageRestoreable(IStorage): """Copying Transactions @@ -1034,8 +948,8 @@ def undo(transaction_id, transaction): This method must only be called in the first phase of two-phase commit (after tpc_begin but before tpc_vote). It returns a serial (transaction id) and a sequence of object ids - for objects affected by the transaction. The serial is ignored - and may be None. + for objects affected by the transaction. + """ # Used by DB (Actually, by TransactionalUndo) From 7824385376cc0a0058a04cac0874319583f39799 Mon Sep 17 00:00:00 2001 From: Jim Fulton Date: Thu, 30 Jun 2016 17:01:46 -0400 Subject: [PATCH 3/5] Define a new interface for storages that support the new commit protocol. This allows interface incompatibilities: - Future version of ZODB that requires the new protocol being configured with a storage that doesn't implement the new protocol - ZEO has a client that uses the old protocol can't use a storage that implements the new protocol. To be caught early. This commit also clarifies that the serial returned by ``undo()`` is ignored. --- src/ZODB/interfaces.py | 90 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 88 insertions(+), 2 deletions(-) diff --git a/src/ZODB/interfaces.py b/src/ZODB/interfaces.py index 716cb0f99..7f6364af7 100644 --- a/src/ZODB/interfaces.py +++ b/src/ZODB/interfaces.py @@ -811,6 +811,92 @@ def tpc_vote(transaction): either from tpc_vote or store for objects passed to store. """ +class IMultiCommitStorage(IStorage): + """A multi-commit storage can commit multiple transactions at once. + + It's lilely that future versions of ZODB will require all storages + to provide this interface. + """ + + def store(oid, serial, data, version, transaction): + """Store data for the object id, oid. + + Arguments: + + oid + The object identifier. This is either a string + consisting of 8 nulls or a string previously returned by + new_oid. + + serial + The serial of the data that was read when the object was + loaded from the database. If the object was created in + the current transaction this will be a string consisting + of 8 nulls. + + data + The data record. This is opaque to the storage. + + version + This must be an empty string. It exists for backward compatibility. + + transaction + A transaction object. This should match the current + transaction for the storage, set by tpc_begin. + + None is returned. + + Several different exceptions may be raised when an error occurs. + + ConflictError + is raised when serial does not match the most recent serial + number for object oid and the conflict was not resolved by + the storage. + + StorageTransactionError + is raised when transaction does not match the current + transaction. + + StorageError or, more often, a subclass of it + is raised when an internal error occurs while the storage is + handling the store() call. + + """ + + def tpc_finish(transaction, func = lambda tid: None): + """Finish the transaction, making any transaction changes permanent. + + Changes must be made permanent at this point. + + This call raises a StorageTransactionError if the storage + isn't participating in two-phase commit. Failure of this + method is extremely serious. + + The second argument is a call-back function that must be + called while the storage transaction lock is held. It takes + the new transaction id generated by the transaction. + + The return value must be the committed tid. It is used to set the + serial for objects whose ids were passed to previous store calls + in the same transaction. + """ + + def tpc_vote(transaction): + """Provide a storage with an opportunity to veto a transaction + + This call raises a StorageTransactionError if the storage + isn't participating in two-phase commit or if it is commiting + a different transaction. + + If a transaction can be committed by a storage, then the + method should return. If a transaction cannot be committed, + then an exception should be raised. If this method returns + without an error, then there must not be an error if + tpc_finish or tpc_abort is called subsequently. + + The return value can be either None or a sequence of oids for which + a conflict was resolved. + """ class IStorageRestoreable(IStorage): """Copying Transactions @@ -948,8 +1034,8 @@ def undo(transaction_id, transaction): This method must only be called in the first phase of two-phase commit (after tpc_begin but before tpc_vote). It returns a serial (transaction id) and a sequence of object ids - for objects affected by the transaction. - + for objects affected by the transaction. The serial is ignored + and may be None. """ # Used by DB (Actually, by TransactionalUndo) From a874d186e2c6d10c4e91fad12b5d5ad1c2325bf3 Mon Sep 17 00:00:00 2001 From: Jim Fulton Date: Fri, 1 Jul 2016 08:44:22 -0400 Subject: [PATCH 4/5] Attempt to simplify and highight the differences between IStorage and IMultiCommitStorage --- src/ZODB/interfaces.py | 86 +++++++----------------------------------- 1 file changed, 13 insertions(+), 73 deletions(-) diff --git a/src/ZODB/interfaces.py b/src/ZODB/interfaces.py index 7f6364af7..f4168972a 100644 --- a/src/ZODB/interfaces.py +++ b/src/ZODB/interfaces.py @@ -776,12 +776,8 @@ def tpc_finish(transaction, func = lambda tid: None): called while the storage transaction lock is held. It takes the new transaction id generated by the transaction. - The return value must be the committed tid. It is used to set the - serial for objects whose ids were passed to previous store calls - in the same transaction. - - For compatibility, the return value can also be None, in which case - store/tpc_vote must return the serial of stored objects. + The return value may be None or the transaction id of the + committed transaction, as described in IMultiCommitStorage. """ def tpc_vote(transaction): @@ -797,16 +793,16 @@ def tpc_vote(transaction): without an error, then there must not be an error if tpc_finish or tpc_abort is called subsequently. - The return value can be either None or a sequence of oids for which - a conflict was resolved. - - For compatibility, the return value can also be a sequence of object-id + The return value can be None or a sequence of object-id and serial pairs giving new serials for objects whose ids were passed to previous store calls in the same transaction. The serial can be the special value ZODB.ConflictResolution.ResolvedSerial to indicate that a conflict occurred and that the object should be invalidated. + The return value can also be a sequence of object ids, as + described in IMultiCommitStorage.tpc_vote. + After the tpc_vote call, all solved conflicts must have been notified, either from tpc_vote or store for objects passed to store. """ @@ -814,69 +810,22 @@ def tpc_vote(transaction): class IMultiCommitStorage(IStorage): """A multi-commit storage can commit multiple transactions at once. - It's lilely that future versions of ZODB will require all storages + It's likely that future versions of ZODB will require all storages to provide this interface. """ def store(oid, serial, data, version, transaction): """Store data for the object id, oid. - Arguments: - - oid - The object identifier. This is either a string - consisting of 8 nulls or a string previously returned by - new_oid. - - serial - The serial of the data that was read when the object was - loaded from the database. If the object was created in - the current transaction this will be a string consisting - of 8 nulls. - - data - The data record. This is opaque to the storage. - - version - This must be an empty string. It exists for backward compatibility. - - transaction - A transaction object. This should match the current - transaction for the storage, set by tpc_begin. - - None is returned. - - Several different exceptions may be raised when an error occurs. - - ConflictError - is raised when serial does not match the most recent serial - number for object oid and the conflict was not resolved by - the storage. - - StorageTransactionError - is raised when transaction does not match the current - transaction. - - StorageError or, more often, a subclass of it - is raised when an internal error occurs while the storage is - handling the store() call. - + See IStorage.store. For object's implementing this interface, + the return value is always None. """ def tpc_finish(transaction, func = lambda tid: None): """Finish the transaction, making any transaction changes permanent. - Changes must be made permanent at this point. - - This call raises a StorageTransactionError if the storage - isn't participating in two-phase commit. Failure of this - method is extremely serious. - - The second argument is a call-back function that must be - called while the storage transaction lock is held. It takes - the new transaction id generated by the transaction. - - The return value must be the committed tid. It is used to set the + See IStorage.store. For object's implementing this interface, + the return value must be the committed tid. It is used to set the serial for objects whose ids were passed to previous store calls in the same transaction. """ @@ -884,17 +833,8 @@ def tpc_finish(transaction, func = lambda tid: None): def tpc_vote(transaction): """Provide a storage with an opportunity to veto a transaction - This call raises a StorageTransactionError if the storage - isn't participating in two-phase commit or if it is commiting - a different transaction. - - If a transaction can be committed by a storage, then the - method should return. If a transaction cannot be committed, - then an exception should be raised. If this method returns - without an error, then there must not be an error if - tpc_finish or tpc_abort is called subsequently. - - The return value can be either None or a sequence of oids for which + See IStorage.store. For object's implementing this interface, + the return value can be either None or a sequence of oids for which a conflict was resolved. """ From d74589ef6169ceb85fe66a0938fc7f6c1d1f4ef2 Mon Sep 17 00:00:00 2001 From: Jim Fulton Date: Fri, 1 Jul 2016 08:48:40 -0400 Subject: [PATCH 5/5] fixed typos --- src/ZODB/interfaces.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/ZODB/interfaces.py b/src/ZODB/interfaces.py index f4168972a..788e6252b 100644 --- a/src/ZODB/interfaces.py +++ b/src/ZODB/interfaces.py @@ -817,14 +817,14 @@ class IMultiCommitStorage(IStorage): def store(oid, serial, data, version, transaction): """Store data for the object id, oid. - See IStorage.store. For object's implementing this interface, + See IStorage.store. For objects implementing this interface, the return value is always None. """ def tpc_finish(transaction, func = lambda tid: None): """Finish the transaction, making any transaction changes permanent. - See IStorage.store. For object's implementing this interface, + See IStorage.store. For objects implementing this interface, the return value must be the committed tid. It is used to set the serial for objects whose ids were passed to previous store calls in the same transaction. @@ -833,7 +833,7 @@ def tpc_finish(transaction, func = lambda tid: None): def tpc_vote(transaction): """Provide a storage with an opportunity to veto a transaction - See IStorage.store. For object's implementing this interface, + See IStorage.store. For objects implementing this interface, the return value can be either None or a sequence of oids for which a conflict was resolved. """