Commit a874d186 authored by Jim Fulton's avatar Jim Fulton

Attempt to simplify and highight the differences between IStorage and IMultiCommitStorage

parent 78243853
...@@ -776,12 +776,8 @@ class IStorage(Interface): ...@@ -776,12 +776,8 @@ class IStorage(Interface):
called while the storage transaction lock is held. It takes called while the storage transaction lock is held. It takes
the new transaction id generated by the transaction. the new transaction id generated by the transaction.
The return value must be the committed tid. It is used to set the The return value may be None or the transaction id of the
serial for objects whose ids were passed to previous store calls committed transaction, as described in IMultiCommitStorage.
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.
""" """
def tpc_vote(transaction): def tpc_vote(transaction):
...@@ -797,16 +793,16 @@ class IStorage(Interface): ...@@ -797,16 +793,16 @@ class IStorage(Interface):
without an error, then there must not be an error if without an error, then there must not be an error if
tpc_finish or tpc_abort is called subsequently. tpc_finish or tpc_abort is called subsequently.
The return value can be either None or a sequence of oids for which The return value can be None or a sequence of object-id
a conflict was resolved.
For compatibility, the return value can also be a sequence of object-id
and serial pairs giving new serials for objects whose ids were and serial pairs giving new serials for objects whose ids were
passed to previous store calls in the same transaction. The serial passed to previous store calls in the same transaction. The serial
can be the special value ZODB.ConflictResolution.ResolvedSerial to can be the special value ZODB.ConflictResolution.ResolvedSerial to
indicate that a conflict occurred and that the object should be indicate that a conflict occurred and that the object should be
invalidated. 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, After the tpc_vote call, all solved conflicts must have been notified,
either from tpc_vote or store for objects passed to store. either from tpc_vote or store for objects passed to store.
""" """
...@@ -814,69 +810,22 @@ class IStorage(Interface): ...@@ -814,69 +810,22 @@ class IStorage(Interface):
class IMultiCommitStorage(IStorage): class IMultiCommitStorage(IStorage):
"""A multi-commit storage can commit multiple transactions at once. """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. to provide this interface.
""" """
def store(oid, serial, data, version, transaction): def store(oid, serial, data, version, transaction):
"""Store data for the object id, oid. """Store data for the object id, oid.
Arguments: See IStorage.store. For object's implementing this interface,
the return value is always None.
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): def tpc_finish(transaction, func = lambda tid: None):
"""Finish the transaction, making any transaction changes permanent. """Finish the transaction, making any transaction changes permanent.
Changes must be made permanent at this point. See IStorage.store. For object's implementing this interface,
the return value must be the committed tid. It is used to set the
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 serial for objects whose ids were passed to previous store calls
in the same transaction. in the same transaction.
""" """
...@@ -884,17 +833,8 @@ class IMultiCommitStorage(IStorage): ...@@ -884,17 +833,8 @@ class IMultiCommitStorage(IStorage):
def tpc_vote(transaction): def tpc_vote(transaction):
"""Provide a storage with an opportunity to veto a transaction """Provide a storage with an opportunity to veto a transaction
This call raises a StorageTransactionError if the storage See IStorage.store. For object's implementing this interface,
isn't participating in two-phase commit or if it is commiting the return value can be either None or a sequence of oids for which
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. a conflict was resolved.
""" """
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment