Commit 02b5cc3c authored by Tim Peters's avatar Tim Peters

Some of the transaction news for 3.3a3 was incorrect, and

more was incomprehensible.  Tried to repair that.  Plus
random improvements to ReST markup.
parent 6d8256d0
......@@ -12,34 +12,38 @@ It was missing the case where the only pending modifications were made
in subtransactions. This has been fixed. If an attempt to close a
connection with pending subtransactions is made now,
ConnnectionStateError: Cannot close a connection with a pending subtransaction
``ConnnectionStateError: Cannot close a connection with a pending subtransaction``
is raised.
transaction
-----------
If ReadConflictError was raised by an attempt to load an object with a
_p_independent() method that returned false, attempting to commit the
transaction failed to (re)raise ReadConflictError for that object. Note
that ZODB intends to prevent committing a transaction in which a
ReadConflictError occurred; this was an obscure case it missed.
Growing pains: ZODB 3.1 and 3.2 had a bug wherein Transaction.begin()
didn't abort the current transaction if the only pending changes were in a
subtransaction. In ZODB 3.3, it's intended that transaction managers be
used instead of invoking methods directly on Transaction objects, and
calling begin() on a transaction manager didn't have this old bug. However,
Transaction.begin() still exists in 3.3, and it had a worse bug: it never
aborted the transaction (not even if changes were pending outside of
subtransactions). Transaction.begin() has been changed to abort the
transaction, although it's still strongly recommended to invoke begin() on
the relevant transaction manager instead. For example,
- Some explanations of new transaction features in the 3.3a3 news
were incorrect, and this news file has been retroactively edited to
repair that. See news for 3.3a3 below.
- If ReadConflictError was raised by an attempt to load an object with a
``_p_independent()`` method that returned false, attempting to commit the
transaction failed to (re)raise ReadConflictError for that object. Note
that ZODB intends to prevent committing a transaction in which a
ReadConflictError occurred; this was an obscure case it missed.
- Growing pains: ZODB 3.1 and 3.2 had a bug wherein ``Transaction.begin()``
didn't abort the current transaction if the only pending changes were in a
subtransaction. In ZODB 3.3, it's intended that transaction managers be
used instead of invoking methods directly on Transaction objects, and
calling ``begin()`` on a transaction manager didn't have this old bug.
However, ``Transaction.begin()`` still exists in 3.3, and it had a worse
bug: it never aborted the transaction (not even if changes were pending
outside of subtransactions). ``Transaction.begin()`` has been changed to
abort the transaction, although it's still strongly recommended to invoke
``begin()`` on the relevant transaction manager instead. For example::
import transaction
transaction.begin()
if using the default ThreadTransactionManager (see news for 3.3a3 below).
if using the default ThreadTransactionManager (see news for 3.3a3 below).
BTrees
------
......@@ -255,9 +259,9 @@ There is a new transaction package, which provides new interfaces for
application code and for the interaction between transactions and
resource managers.
The top-level transaction package has functions commit(), abort(),
get(), and begin(). They should be used instead of the magic
get_transaction() builtin, which will be deprecated. For example:
The top-level transaction package has functions ``commit()``, ``abort()``,
``get()``, and ``begin()``. They should be used instead of the magic
``get_transaction()`` builtin, which will be deprecated. For example:
>>> get_transaction().commit()
......@@ -266,38 +270,38 @@ should now be written as
>>> import transaction
>>> transaction.commit()
The new API provides explicit transaction manager objects. The
transaction manager (TM) is responsible for associating resource
managers with a "current" transaction. It is available as
`transaction.manager`. The default TM, implemented by
ThreadedTransactionManager, assigns each thread its own current
transaction. The TransactionManager class assigns all threads to the
same transaction.
The new API provides explicit transaction manager objects. A transaction
manager (TM) is responsible for associating resource managers with a
"current" transaction. The default TM, implemented by class
``ThreadedTransactionManager``, assigns each thread its own current
transaction. This default TM is available as ``transaction.manager``. The
``TransactionManager`` class assigns all threads to the same transaction,
and is an explicit replacement for the ``Connection.setLocalTransaction()``
method:
A transaction manager instance can be passed as the txn_mgr argument
to DB.open(). If you do, the connection will use the specified
transaction manager instead of the default transaction manager. You
will need to call commit() and abort() on the transaction manager
explicitly. For example:
A transaction manager instance can be passed as the txn_mgr argument to
``DB.open()``. If you do, the connection will use the specified
transaction manager instead of the default TM. The current transaction is
obtained by calling ``get()`` on a TM. For example:
>>> tm = transaction.TransactionManager()
>>> cn = db.open(txn_mgr=tm)
[...]
>>> tm.commit()
>>> tm.get().commit()
The setLocalTransaction() and getTransaction() methods of Connection
are deprecated. Use an explicit TM passed via txn_mgr instead. The
setLocalTransaction() manager functions still works, but it returns a
TM instead of a Transaction.
The ``setLocalTransaction()`` and ``getTransaction()`` methods of
Connection are deprecated. Use an explicit TM passed via ``txn_mgr=`` to
``DB.open()`` instead. The ``setLocalTransaction()`` method still works,
but it returns a TM instead of a Transaction.
The TM creates Transaction objects, which are used for exactly one
transaction. They have a status() method that returns their current
state.
A TM creates Transaction objects, which are used for exactly one
transaction. Transaction objects still have ``commit()``, ``abort()``,
``note()``, ``setUser()``, and ``setExtendedInfo()`` methods.
Resource managers, e.g. Connection or RDB adapter, should use join()
instead of register(). An object that calls join() manages its own
resources. An object that calls register() expects the TM to manage
the objects.
Resource managers, e.g. Connection or RDB adapter, should use a
Transaction's ``join()`` method instead of its ``register()`` method. An
object that calls ``join()`` manages its own resources. An object that
calls ``register()`` expects the TM to manage the objects.
Data managers written against the ZODB 4 transaction API are now
supported in ZODB 3.
......
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