Skip to content

Z
ZODB
Commit c3c6a9e8 authored by Stephan Richter's avatar Stephan Richter
Browse files
Options

Merge from trunk

parent f5fa221c
Hide whitespace changes
Inline Side-by-side
Showing with 144 additions and 116 deletions
src/ZODB/collaborations.txt
View file @ c3c6a9e8
=======================
Collabortation Diagrams
=======================
This file contains several collaboration diagrams for the ZODB.
Simple fetch, modify, commit
============================
Participants
DB: ZODB.DB.DB
C: ZODB.Connection.Connection
S: ZODB.FileStorage.FileStorage
T: transaction.interfaces.ITransaction
TM: transaction.interfaces.ITransactionManager
o1, o2, ...: pre-existing persistent objects
------------
- ``DB``: ``ZODB.DB.DB``
- ``C``: ``ZODB.Connection.Connection``
- ``S``: ``ZODB.FileStorage.FileStorage``
- ``T``: ``transaction.interfaces.ITransaction``
- ``TM``: ``transaction.interfaces.ITransactionManager``
- ``o1``, ``o2``, ...: pre-existing persistent objects
Scenario
"""Simple fetch, modify, commit."""
--------
::
DB.open()
create C
......@@ -50,16 +63,23 @@ Scenario
# transactions.
Simple fetch, modify, abort
===========================
Participants
DB: ZODB.DB.DB
C: ZODB.Connection.Connection
S: ZODB.FileStorage.FileStorage
T: transaction.interfaces.ITransaction
TM: transaction.interfaces.ITransactionManager
o1, o2, ...: pre-existing persistent objects
------------
- ``DB``: ``ZODB.DB.DB``
- ``C``: ``ZODB.Connection.Connection``
- ``S``: ``ZODB.FileStorage.FileStorage``
- ``T``: ``transaction.interfaces.ITransaction``
- ``TM``: ``transaction.interfaces.ITransactionManager``
- ``o1``, ``o2``, ...: pre-existing persistent objects
Scenario
"""Simple fetch, modify, abort."""
--------
::
DB.open()
create C
......@@ -91,15 +111,22 @@ Scenario
# transactions.
Participants:
T: ITransaction
o1, o2, o3: some persistent objects
C1, C2, C3: resource managers
S1, S2: Transaction savepoint objects
s11, s21, s22: resource-manager savepoints
Rollback of a savepoint
=======================
Participants
------------
- ``T``: ``transaction.interfaces.ITransaction``
- ``o1``, ``o2``, ``o3``: some persistent objects
- ``C1``, ``C2``, ``C3``: resource managers
- ``S1``, ``S2``: Transaction savepoint objects
- ``s11``, ``s21``, ``s22``: resource-manager savepoints
Scenario
"""Rollback of a savepoint"""
--------
::
create T
o1.modify()
......@@ -140,8 +167,8 @@ Scenario
o2.invalidate()
# truncates temporary storage to beginning, because
# s22 was the first savepoint. (Perhaps conection
# savepoints record the log position before the
# data were written, which is 0 in this case.
# savepoints record the log position before the
# data were written, which is 0 in this case.
T.commit()
C1.beforeCompletion(T)
C2.beforeCompletion(T)
......
src/ZODB/cross-database-references.txt
View file @ c3c6a9e8
=========================
Cross-Database References
=========================
......@@ -36,7 +37,7 @@ We'll have a reference to the first object:
>>> tm.commit()
Now, let's open a separate connection to database 2. We use it to
read p2, use p2 to get to p1, and verify that it is in database 1:
read `p2`, use `p2` to get to `p1`, and verify that it is in database 1:
>>> conn = db2.open()
>>> p2x = conn.root()['p']
......@@ -77,8 +78,8 @@ happens. Consider:
>>> p1.p4 = p4
>>> p2.p4 = p4
In this example, the new object is reachable from both p1 in database
1 and p2 in database 2. If we commit, which database will p4 end up
In this example, the new object is reachable from both `p1` in database
1 and `p2` in database 2. If we commit, which database will `p4` end up
in? This sort of ambiguity can lead to subtle bugs. For that reason,
an error is generated if we commit changes when new objects are
reachable from multiple databases:
......@@ -126,7 +127,7 @@ to explicitly say waht database an object belongs to:
>>> p1.p5 = p5
>>> p2.p5 = p5
>>> conn1.add(p5)
>>> tm.commit()
>>> tm.commit()
>>> p5._p_jar.db().database_name
'1'
......@@ -141,6 +142,7 @@ cross-database references, however, there are a number of facilities
missing:
cross-database garbage collection
Garbage collection is done on a database by database basis.
If an object on a database only has references to it from other
databases, then the object will be garbage collected when its
......@@ -148,11 +150,13 @@ cross-database garbage collection
broken.
cross-database undo
Undo is only applied to a single database. Fixing this for
multiple databases is going to be extremely difficult. Undo
currently poses consistency problems, so it is not (or should not
be) widely used.
Cross-database aware (tolerant) export/import
The export/import facility needs to be aware, at least, of cross-database
references.
src/ZODB/persistentclass.txt
View file @ c3c6a9e8
==================
Persistent Classes
==================
......@@ -39,7 +40,7 @@ functions to make them picklable.
Also note that we explictly set the module. Persistent classes don't
live in normal Python modules. Rather, they live in the database. We
use information in __module__ to record where in the database. When
use information in ``__module__`` to record where in the database. When
we want to use a database, we will need to supply a custom class
factory to load instances of the class.
......@@ -189,7 +190,7 @@ database:
NOTE: If a non-persistent instance of a persistent class is copied,
the class may be copied as well. This is usually not the desired
result.
result.
Persistent instances of persistent classes
......@@ -228,10 +229,10 @@ Now, if we try to load it, we get a broken oject:
>>> connection2.root()['obs']['p']
<persistent broken __zodb__.P instance '\x00\x00\x00\x00\x00\x00\x00\x04'>
because the module, "__zodb__" can't be loaded. We need to provide a
because the module, `__zodb__` can't be loaded. We need to provide a
class factory that knows about this special module. Here we'll supply a
sample class factory that looks up a class name in the database root
if the module is "__zodb__". It falls back to the normal class lookup
if the module is `__zodb__`. It falls back to the normal class lookup
for other modules:
>>> from ZODB.broken import find_global
......@@ -242,7 +243,7 @@ for other modules:
>>> some_database.classFactory = classFactory
Normally, the classFactory should be set before a database is opened.
Normally, the classFactory should be set before a database is opened.
We'll reopen the connections we're using. We'll assign the old
connections to a variable first to prevent getting them from the
connection pool:
......@@ -250,7 +251,7 @@ connection pool:
>>> old = connection, connection2
>>> connection = some_database.open(transaction_manager=tm)
>>> connection2 = some_database.open(transaction_manager=tm2)
Now, we can read the object:
>>> connection2.root()['obs']['p'].color
......
src/ZODB/subtransactions.txt
View file @ c3c6a9e8
......@@ -8,44 +8,44 @@ subtransactions. When a transaction is committed, a flag is passed
indicating whether it is a subtransaction or a top-level transaction.
Consider the following exampler commit calls:
- commit()
- ``commit()``
A regular top-level transaction is committed.
- commit(1)
- ``commit(1)``
A subtransaction is committed. There is now one subtransaction of
the current top-level transaction.
- commit(1)
- ``commit(1)``
A subtransaction is committed. There are now two subtransactions of
the current top-level transaction.
- abort(1)
- ``abort(1)``
A subtransaction is aborted. There are still two subtransactions of
the current top-level transaction; work done since the last
commit(1) call is discarded.
``commit(1)`` call is discarded.
- commit()
- ``commit()``
We now commit a top-level transaction. The work done in the previous
two subtransactions *plus* work done since the last abort(1) call
two subtransactions *plus* work done since the last ``abort(1)`` call
is saved.
- commit(1)
- ``commit(1)``
A subtransaction is committed. There is now one subtransaction of
the current top-level transaction.
- commit(1)
- ``commit(1)``
A subtransaction is committed. There are now two subtransactions of
the current top-level transaction.
- abort()
- ``abort()``
We now abort a top-level transaction. We discard the work done in
the previous two subtransactions *plus* work done since the last
commit(1) call.
``commit(1)`` call.
src/ZODB/tests/multidb.txt
View file @ c3c6a9e8
##############################################################################
#
# Copyright (c) 2005 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
Multi-database tests
====================
==================
Multiple Databases
==================
Multi-database support adds the ability to tie multiple databases into a
collection. The original proposal is in the fishbowl:
......@@ -25,29 +12,29 @@ by Jim Fulton, Christian Theune, and Tim Peters. Overview:
No private attributes were added, and one new method was introduced.
DB:
``DB``:
- a new .database_name attribute holds the name of this database
- a new ``.database_name`` attribute holds the name of this database.
- a new .databases attribute maps from database name to DB object; all DBs
in a multi-database collection share the same .databases object
- a new ``.databases`` attribute maps from database name to ``DB`` object; all
databases in a multi-database collection share the same ``.databases`` object
- the DB constructor has new optional arguments with the same names
(database_name= and databases=).
- the ``DB`` constructor has new optional arguments with the same names
(``database_name=`` and ``databases=``).
Connection:
``Connection``:
- a new .connections attribute maps from database name to a Connection for
the database with that name; the .connections mapping object is also
shared among databases in a collection
- a new ``.connections`` attribute maps from database name to a ``Connection``
for the database with that name; the ``.connections`` mapping object is also
shared among databases in a collection.
- a new .get_connection(database_name) method returns a Connection for a
database in the collection; if a connection is already open, it's returned
(this is the value .connections[database_name]), else a new connection is
opened (and stored as .connections[database_name])
- a new ``.get_connection(database_name)`` method returns a ``Connection`` for
a database in the collection; if a connection is already open, it's returned
(this is the value ``.connections[database_name]``), else a new connection
is opened (and stored as ``.connections[database_name]``)
Creating a multi-database starts with creating a named DB:
Creating a multi-database starts with creating a named ``DB``:
>>> from ZODB.tests.test_storage import MinimalMemoryStorage
>>> from ZODB import DB
......@@ -69,7 +56,8 @@ Adding another database to the collection works like this:
... database_name='notroot',
... databases=dbmap)
The new db2 now shares the 'databases' dictionary with db and has two entries:
The new ``db2`` now shares the ``databases`` dictionary with db and has two
entries:
>>> db2.databases is db.databases is dbmap
True
......@@ -87,7 +75,7 @@ It's an error to try to insert a database with a name already in use:
...
ValueError: database_name 'root' already in databases
Because that failed, db.databases wasn't changed:
Because that failed, ``db.databases`` wasn't changed:
>>> len(db.databases) # still 2
2
......@@ -127,7 +115,7 @@ Now there are two connections in that collection:
>>> names = cn.connections.keys(); names.sort(); print names
['notroot', 'root']
So long as this database group remains open, the same Connection objects
So long as this database group remains open, the same ``Connection`` objects
are returned:
>>> cn.get_connection('root') is cn
......@@ -152,6 +140,7 @@ Clean up:
>>> for a_db in dbmap.values():
... a_db.close()
Configuration from File
-----------------------
......@@ -171,8 +160,8 @@ ZODB 3.6:
>>> db.databases.keys()
['this_is_the_name']
However, the .databases attribute cannot be configured from file. It
can be passed to the ZConfig factory. I'm not sure of the clearest way
However, the ``.databases`` attribute cannot be configured from file. It
can be passed to the `ZConfig` factory. I'm not sure of the clearest way
to test that here; this is ugly:
>>> from ZODB.config import getDbSchema
......@@ -184,13 +173,13 @@ different database_name:
>>> config2 = config.replace("this_is_the_name", "another_name")
Now get a ZConfig factory from `config2`:
Now get a `ZConfig` factory from `config2`:
>>> f = StringIO(config2)
>>> zconfig, handle = ZConfig.loadConfigFile(getDbSchema(), f)
>>> factory = zconfig.database
The desired `databases` mapping can be passed to this factory:
The desired ``databases`` mapping can be passed to this factory:
>>> db2 = factory.open(databases=db.databases)
>>> print db2.database_name # has the right name
......
src/ZODB/tests/synchronizers.txt
View file @ c3c6a9e8
Here are some tests that storage sync() methods get called at appropriate
=============
Synchronizers
=============
Here are some tests that storage ``sync()`` methods get called at appropriate
times in the life of a transaction. The tested behavior is new in ZODB 3.4.
First define a lightweight storage with a sync() method:
First define a lightweight storage with a ``sync()`` method:
>>> import ZODB
>>> from ZODB.MappingStorage import MappingStorage
......@@ -27,14 +31,14 @@ Sync should not have been called yet.
False
sync is called by the Connection's afterCompletion() hook after the commit
completes.
``sync()`` is called by the Connection's ``afterCompletion()`` hook after the
commit completes.
>>> transaction.commit()
>>> st.sync_called # False before 3.4
True
sync is also called by the afterCompletion() hook after an abort.
``sync()`` is also called by the ``afterCompletion()`` hook after an abort.
>>> st.sync_called = False
>>> rt['b'] = 2
......@@ -42,8 +46,8 @@ sync is also called by the afterCompletion() hook after an abort.
>>> st.sync_called # False before 3.4
True
And sync is called whenever we explicitly start a new txn, via the
newTransaction() hook.
And ``sync()`` is called whenever we explicitly start a new transaction, via
the ``newTransaction()`` hook.
>>> st.sync_called = False
>>> dummy = transaction.begin()
......@@ -51,19 +55,19 @@ newTransaction() hook.
True
Clean up. Closing db isn't enough -- closing a DB doesn't close its
Connections. Leaving our Connection open here can cause the
SimpleStorage.sync() method to get called later, during another test, and
our doctest-synthesized module globals no longer exist then. You get
a weird traceback then ;-)
`Connections`. Leaving our `Connection` open here can cause the
``SimpleStorage.sync()`` method to get called later, during another test, and
our doctest-synthesized module globals no longer exist then. You get a weird
traceback then ;-)
>>> cn.close()
One more, very obscure. It was the case that if the first action a new
threaded transaction manager saw was a begin() call, then synchronizers
registered after that in the same transaction weren't communicated to
the Transaction object, and so the synchronizers' afterCompletion() hooks
threaded transaction manager saw was a ``begin()`` call, then synchronizers
registered after that in the same transaction weren't communicated to the
`Transaction` object, and so the synchronizers' ``afterCompletion()`` hooks
weren't called when the transaction commited. None of the test suites
(ZODB's, Zope 2.8's, or Zope3's) caught that, but apparently Zope3 takes this
(ZODB's, Zope 2.8's, or Zope3's) caught that, but apparently Zope 3 takes this
path at some point when serving pages.
>>> tm = transaction.ThreadTransactionManager()
......@@ -75,14 +79,14 @@ path at some point when serving pages.
>>> st.sync_called
False
Now ensure that cn.afterCompletion() -> st.sync() gets called by commit
despite that the Connection registered after the transaction began:
Now ensure that ``cn.afterCompletion() -> st.sync()`` gets called by commit
despite that the `Connection` registered after the transaction began:
>>> tm.commit()
>>> st.sync_called
True
And try the same thing with a non-threaded TM:
And try the same thing with a non-threaded transaction manager:
>>> cn.close()
>>> tm = transaction.TransactionManager()
......
src/ZODB/tests/testConnectionSavepoint.txt
View file @ c3c6a9e8
==========
Savepoints
==========
Savepoints provide a way to save to disk intermediate work done during
a transaction allowing:
Savepoints provide a way to save to disk intermediate work done during a
transaction allowing:
- partial transaction (subtransaction) rollback (abort)
- state of saved objects to be freed, freeing on-line memory for other
uses
Savepoints make it possible to write atomic subroutines that don't
make top-level transaction commitments.
Savepoints make it possible to write atomic subroutines that don't make
top-level transaction commitments.
Applications
------------
......@@ -39,13 +41,13 @@ and abort changes:
>>> root['name']
'bob'
Now, let's look at an application that manages funds for people.
It allows deposits and debits to be entered for multiple people.
It accepts a sequence of entries and generates a sequence of status
messages. For each entry, it applies the change and then validates
the user's account. If the user's account is invalid, we roll back
the change for that entry. The success or failure of an entry is
indicated in the output status. First we'll initialize some accounts:
Now, let's look at an application that manages funds for people. It allows
deposits and debits to be entered for multiple people. It accepts a sequence
of entries and generates a sequence of status messages. For each entry, it
applies the change and then validates the user's account. If the user's
account is invalid, we roll back the change for that entry. The success or
failure of an entry is indicated in the output status. First we'll initialize
some accounts:
>>> root['bob-balance'] = 0.0
>>> root['bob-credit'] = 0.0
......@@ -59,8 +61,8 @@ Now, we'll define a validation function to validate an account:
... if root[name+'-balance'] + root[name+'-credit'] < 0:
... raise ValueError('Overdrawn', name)
And a function to apply entries. If the function fails in some
unexpected way, it rolls back all of its changes and prints the error:
And a function to apply entries. If the function fails in some unexpected
way, it rolls back all of its changes and prints the error:
>>> def apply_entries(entries):
... savepoint = transaction.savepoint()
......@@ -114,9 +116,9 @@ If we provide entries that cause an unexpected error:
Updated sally
Unexpected exception unsupported operand type(s) for +=: 'float' and 'str'
Because the apply_entries used a savepoint for the entire function,
it was able to rollback the partial changes without rolling back
changes made in the previous call to apply_entries:
Because the apply_entries used a savepoint for the entire function, it was
able to rollback the partial changes without rolling back changes made in the
previous call to ``apply_entries``:
>>> root['bob-balance']
30.0
......@@ -135,6 +137,7 @@ away:
>>> root['sally-balance']
0.0
Savepoint invalidation
----------------------
......
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7