[Zodb-checkins] SVN: ZODB/branches/3.6/src/ZODB/ Merge from trunk
Stephan Richter
srichter at cosmos.phy.tufts.edu
Sat Nov 5 08:55:27 EST 2005
Log message for revision 39914:
Merge from trunk
Changed:
U ZODB/branches/3.6/src/ZODB/collaborations.txt
U ZODB/branches/3.6/src/ZODB/cross-database-references.txt
U ZODB/branches/3.6/src/ZODB/persistentclass.txt
U ZODB/branches/3.6/src/ZODB/subtransactions.txt
U ZODB/branches/3.6/src/ZODB/tests/multidb.txt
U ZODB/branches/3.6/src/ZODB/tests/synchronizers.txt
U ZODB/branches/3.6/src/ZODB/tests/testConnectionSavepoint.txt
-=-
Modified: ZODB/branches/3.6/src/ZODB/collaborations.txt
===================================================================
--- ZODB/branches/3.6/src/ZODB/collaborations.txt 2005-11-05 13:55:15 UTC (rev 39913)
+++ ZODB/branches/3.6/src/ZODB/collaborations.txt 2005-11-05 13:55:26 UTC (rev 39914)
@@ -1,14 +1,27 @@
+=======================
+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
TM.registerSynch(C)
@@ -50,17 +63,24 @@
# 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
TM.registerSynch(C)
@@ -91,16 +111,23 @@
# 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()
C1.regisiter(o1)
@@ -140,8 +167,8 @@
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)
Modified: ZODB/branches/3.6/src/ZODB/cross-database-references.txt
===================================================================
--- ZODB/branches/3.6/src/ZODB/cross-database-references.txt 2005-11-05 13:55:15 UTC (rev 39913)
+++ ZODB/branches/3.6/src/ZODB/cross-database-references.txt 2005-11-05 13:55:26 UTC (rev 39914)
@@ -1,3 +1,4 @@
+=========================
Cross-Database References
=========================
@@ -36,7 +37,7 @@
>>> 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 @@
>>> 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 @@
>>> p1.p5 = p5
>>> p2.p5 = p5
>>> conn1.add(p5)
- >>> tm.commit()
+ >>> tm.commit()
>>> p5._p_jar.db().database_name
'1'
@@ -141,6 +142,7 @@
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 @@
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.
Modified: ZODB/branches/3.6/src/ZODB/persistentclass.txt
===================================================================
--- ZODB/branches/3.6/src/ZODB/persistentclass.txt 2005-11-05 13:55:15 UTC (rev 39913)
+++ ZODB/branches/3.6/src/ZODB/persistentclass.txt 2005-11-05 13:55:26 UTC (rev 39914)
@@ -1,3 +1,4 @@
+==================
Persistent Classes
==================
@@ -39,7 +40,7 @@
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 @@
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 @@
>>> 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 @@
>>> 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 @@
>>> 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
Modified: ZODB/branches/3.6/src/ZODB/subtransactions.txt
===================================================================
--- ZODB/branches/3.6/src/ZODB/subtransactions.txt 2005-11-05 13:55:15 UTC (rev 39913)
+++ ZODB/branches/3.6/src/ZODB/subtransactions.txt 2005-11-05 13:55:26 UTC (rev 39914)
@@ -8,44 +8,44 @@
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.
Modified: ZODB/branches/3.6/src/ZODB/tests/multidb.txt
===================================================================
--- ZODB/branches/3.6/src/ZODB/tests/multidb.txt 2005-11-05 13:55:15 UTC (rev 39913)
+++ ZODB/branches/3.6/src/ZODB/tests/multidb.txt 2005-11-05 13:55:26 UTC (rev 39914)
@@ -1,20 +1,7 @@
-##############################################################################
-#
-# 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.
-#
-##############################################################################
+==================
+Multiple Databases
+==================
-Multi-database tests
-====================
-
Multi-database support adds the ability to tie multiple databases into a
collection. The original proposal is in the fishbowl:
@@ -25,29 +12,29 @@
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 @@
... 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 @@
...
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 @@
>>> 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 @@
>>> for a_db in dbmap.values():
... a_db.close()
+
Configuration from File
-----------------------
@@ -171,8 +160,8 @@
>>> 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 @@
>>> 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
Modified: ZODB/branches/3.6/src/ZODB/tests/synchronizers.txt
===================================================================
--- ZODB/branches/3.6/src/ZODB/tests/synchronizers.txt 2005-11-05 13:55:15 UTC (rev 39913)
+++ ZODB/branches/3.6/src/ZODB/tests/synchronizers.txt 2005-11-05 13:55:26 UTC (rev 39914)
@@ -1,7 +1,11 @@
-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 @@
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 @@
>>> 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 @@
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 @@
>>> 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()
Modified: ZODB/branches/3.6/src/ZODB/tests/testConnectionSavepoint.txt
===================================================================
--- ZODB/branches/3.6/src/ZODB/tests/testConnectionSavepoint.txt 2005-11-05 13:55:15 UTC (rev 39913)
+++ ZODB/branches/3.6/src/ZODB/tests/testConnectionSavepoint.txt 2005-11-05 13:55:26 UTC (rev 39914)
@@ -1,17 +1,19 @@
+==========
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 @@
>>> 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 @@
... 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 @@
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 @@
>>> root['sally-balance']
0.0
+
Savepoint invalidation
----------------------
More information about the Zodb-checkins
mailing list