[Zope3-checkins] CVS: ZODB/src/ZODB - BaseStorage.py:1.45

[Jeremy Hylton]

Update of /cvs-repository/ZODB/src/ZODB
In directory cvs.zope.org:/tmp/cvs-serv13551

Modified Files:
	BaseStorage.py 
Log Message:
Add modified version of docstring from ZODB 4.


=== ZODB/src/ZODB/BaseStorage.py 1.44 => 1.45 ===
--- ZODB/src/ZODB/BaseStorage.py:1.44	Thu Feb 26 19:31:53 2004
+++ ZODB/src/ZODB/BaseStorage.py	Thu Mar 11 11:41:03 2004
@@ -28,6 +28,54 @@
 from ZODB.UndoLogCompatible import UndoLogCompatible
 
 class BaseStorage(UndoLogCompatible):
+    """Abstract base class that support storage implementations.
+
+    A subclass must define the following methods:
+    load()
+    close()
+    cleanup()
+    lastSerial()
+    lastTransaction()
+
+    It must override these hooks:
+    _begin()
+    _vote()
+    _abort()
+    _finish()
+    _clear_temp()
+
+    If it stores multiple revisions, it should implement
+    loadSerial()
+    loadBefore()
+    iterator()
+
+    If the subclass wants to implement undo, it should implement the
+    multiple revision methods and:
+    loadSerial()
+    undo()
+    undoInfo()
+    undoLog()
+
+    If the subclass wants to implement versions, it must implement:
+    abortVersion()
+    commitVersion()
+    modifiedInVersion()
+    versionEmpty()
+    versions()
+
+    Each storage will have two locks that are accessed via lock
+    acquire and release methods bound to the instance.  (Yuck.)
+    _lock_acquire / _lock_release (reentrant)
+    _commit_lock_acquire / _commit_lock_release
+
+    The commit lock is acquired in tpc_begin() and released in
+    tpc_abort() and tpc_finish().  It is never acquired with the other
+    lock held.
+
+    The other lock appears to protect _oid and _transaction and
+    perhaps other things.  It is always held when load() is called, so
+    presumably the load() implementation should also acquire the lock.
+    """    
     _transaction=None # Transaction that is being committed
     _tstatus=' '      # Transaction status, used for copying data
     _is_read_only = False