Commit ed365135 authored by Jim Fulton's avatar Jim Fulton

Documentation on transactions and threading.

This adds documentatuon on transactions and threading concerns.

There are some topics, like application design and conflict resolution
that might want a deeper treatment, but would probably be better
handled through articles or dedicated topics. (I want to avoid
individual topics being too long or weedy to read, where practical.)

Writing this, I stumbled a bit over thread-local transaction managers.
For most applications, they don't add anything over accessing
transaction managers on connections and actually provide an
opportunity to fail. I'm convinced that it should be possible to do
most transaction management through connections and that the API
provided by transaction managers and the transaction package should be
reserved for distributed transactions.

I didn't mention gevent. I thik there should be a section on gevent,
but I think it should be written by someone who's used gevent with
ZODB. :)

Maybe there should also be a section or mention of using asyncio with
ZODB, pr maybe later.

Closes zopefoundation/zodbdocs#13
Closes zopefoundation/zodbdocs#16
parent d6b60a5b
...@@ -2,7 +2,7 @@ ...@@ -2,7 +2,7 @@
Change History Change History
================ ================
5.0.1 (unreleased) 5.0.1 (2016-09-09)
================== ==================
- Fix an AttributeError that DemoStorage could raise if it was asked - Fix an AttributeError that DemoStorage could raise if it was asked
...@@ -12,6 +12,8 @@ ...@@ -12,6 +12,8 @@
- Call _p_resolveConflict() even if a conflicting change doesn't change the - Call _p_resolveConflict() even if a conflicting change doesn't change the
state. This reverts to the behaviour of 3.10.3 and older. state. This reverts to the behaviour of 3.10.3 and older.
- Many docstrings have been improved.
5.0.0 (2016-09-06) 5.0.0 (2016-09-06)
================== ==================
......
...@@ -435,7 +435,7 @@ new schema. This can be easy if your network of object references is quite ...@@ -435,7 +435,7 @@ new schema. This can be easy if your network of object references is quite
structured, making it easy to find all the instances of the class being structured, making it easy to find all the instances of the class being
modified. For example, if all :class:`User` objects can be found inside a modified. For example, if all :class:`User` objects can be found inside a
single dictionary or BTree, then it would be a simple matter to loop over every single dictionary or BTree, then it would be a simple matter to loop over every
:class:`User` instance with a :keyword:`for` statement. This is more difficult :class:`User` instance with a ``for`` statement. This is more difficult
if your object graph is less structured; if :class:`User` objects can be found if your object graph is less structured; if :class:`User` objects can be found
as attributes of any number of different class instances, then there's no longer as attributes of any number of different class instances, then there's no longer
any easy way to find them all, short of writing a generalized object traversal any easy way to find them all, short of writing a generalized object traversal
......
...@@ -14,13 +14,11 @@ If you haven't yet, you should read the :ref:`Tutorial <tutorial-label>`. ...@@ -14,13 +14,11 @@ If you haven't yet, you should read the :ref:`Tutorial <tutorial-label>`.
install-and-run install-and-run
writing-persistent-objects.rst writing-persistent-objects.rst
transactions-and-threading
.. todo: .. todo:
transaction.rst blobs
storages.rst packing-and-garbage-collection
configuration.rst multi-databases
threading.rst blobs
packing-and-garbage-collection.rst
blobs.rst
multi-databases.rst
...@@ -128,6 +128,8 @@ much of anything. Connections take care of loading and saving objects ...@@ -128,6 +128,8 @@ much of anything. Connections take care of loading and saving objects
and manage object caches. Each connection has it's own cache and manage object caches. Each connection has it's own cache
[#caches-are-expensive]_. [#caches-are-expensive]_.
.. _getting-connections:
Getting connections Getting connections
------------------- -------------------
...@@ -144,7 +146,7 @@ db.open() ...@@ -144,7 +146,7 @@ db.open()
done using the connection. done using the connection.
If changes are made, the application :ref:`commits transactions If changes are made, the application :ref:`commits transactions
<commit-transactions>` to make them permanent. <using-transactions-label>` to make them permanent.
db.transaction() db.transaction()
The database :meth:`~ZODB.DB.transaction` method The database :meth:`~ZODB.DB.transaction` method
......
This diff is collapsed.
...@@ -6,6 +6,6 @@ Reference Documentation ...@@ -6,6 +6,6 @@ Reference Documentation
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
zodb.rst zodb
storages.rst storages
transaction
============
Transactions
============
Transaction support is provided by the `transaction
<http://transaction.readthedocs.io/en/latest/>`_ package, which is
installed automatically when you install ZODB. There are 2 important
APIs provided by the transaction package, ``ITransactionManager`` and
``ITransaction``, described below.
ITransactionManager
===================
.. autointerface:: transaction.interfaces.ITransactionManager
:members: begin, get, commit, abort, doom, isDoomed, savepoint
ITransaction
============
.. autointerface:: transaction.interfaces.ITransaction
:members: user, description, commit, abort, doom, savepoint, note,
setUser, setExtendedInfo,
addBeforeCommitHook, getBeforeCommitHooks,
addAfterCommitHook, getAfterCommitHooks
...@@ -84,7 +84,8 @@ Connections ...@@ -84,7 +84,8 @@ Connections
.. autoclass:: ZODB.Connection.Connection .. autoclass:: ZODB.Connection.Connection
:members: add, cacheGC, cacheMinimize, close, db, get, :members: add, cacheGC, cacheMinimize, close, db, get,
getDebugInfo, get_connection, isReadOnly, oldstate, getDebugInfo, get_connection, isReadOnly, oldstate,
onCloseCallback, root, setDebugInfo, sync onCloseCallback, root, setDebugInfo, sync,
transaction_manager
TimeStamp (transaction ids) TimeStamp (transaction ids)
=========================== ===========================
......
...@@ -50,6 +50,8 @@ import six ...@@ -50,6 +50,8 @@ import six
from .mvccadapter import HistoricalStorageAdapter from .mvccadapter import HistoricalStorageAdapter
from . import valuedoc
global_reset_counter = 0 global_reset_counter = 0
noop = lambda : None noop = lambda : None
...@@ -88,6 +90,9 @@ class Connection(ExportImport, object): ...@@ -88,6 +90,9 @@ class Connection(ExportImport, object):
_code_timestamp = 0 _code_timestamp = 0
#: Transaction manager associated with the connection when it was opened.
transaction_manager = valuedoc.ValueDoc('current transaction manager')
########################################################################## ##########################################################################
# Connection methods, ZODB.IConnection # Connection methods, ZODB.IConnection
......
...@@ -43,6 +43,7 @@ def test_suite(): ...@@ -43,6 +43,7 @@ def test_suite():
manuel.doctest.Manuel() + manuel.capture.Manuel(), manuel.doctest.Manuel() + manuel.capture.Manuel(),
join(guide, 'writing-persistent-objects.rst'), join(guide, 'writing-persistent-objects.rst'),
join(guide, 'install-and-run.rst'), join(guide, 'install-and-run.rst'),
join(guide, 'transactions-and-threading.rst'),
join(reference, 'zodb.rst'), join(reference, 'zodb.rst'),
join(reference, 'storages.rst'), join(reference, 'storages.rst'),
setUp=setUp, tearDown=tearDown, setUp=setUp, tearDown=tearDown,
......
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