[Zope-Checkins] CVS: ZODB3/ZEO - cache.py:1.1.2.2

[Jeremy Hylton]

Update of /cvs-repository/ZODB3/ZEO
In directory cvs.zope.org:/tmp/cvs-serv28671/ZEO

Modified Files:
      Tag: ZODB3-mvcc-2-branch
	cache.py 
Log Message:
Add some text explaining how the cache works.
Revise version handling to store a tid.
Add a close() method to make tests happy.


=== ZODB3/ZEO/cache.py 1.1.2.1 => 1.1.2.2 ===
--- ZODB3/ZEO/cache.py:1.1.2.1	Tue Nov  4 15:04:37 2003
+++ ZODB3/ZEO/cache.py	Wed Nov  5 23:35:21 2003
@@ -21,6 +21,27 @@
 # server.
 # <p>
 # The details of the constructor as unspecified at this point.
+# <p>
+# Each entry in the cache is valid for a particular range of transaction
+# ids.  The lower bound is the transaction that wrote the data.  The
+# upper bound is the next transaction that wrote a revision of the
+# object.  If the data is current, the upper bound is stored as None;
+# the data is considered current until an invalidate() call is made.
+# <p>
+# It is an error to call store() twice with the same object without an
+# intervening invalidate() to set the upper bound on the first cache
+# entry.  <em>Perhaps it will be necessary to have a call the removes
+# something from the cache outright, without keeping a non-current
+# entry.</em>
+# <h3>Cache verification</h3>
+# <p>
+# When the client is connected to the server, it receives
+# invalidations every time an object is modified.  Whe the client is
+# disconnected, it must perform cache verification to make sure its
+# cached data is synchronized with the storage's current state.
+
+# quick verification
+# full verification
 
 class Cache:
     """A simple in-memory cache."""
@@ -32,6 +53,11 @@
         self.version = {}
         self.noncurrent = {}
 
+    # XXX perhaps we need an open, too
+
+    def close(self):
+        pass
+
     ##
     # Set the last transaction seen by the cache.
     # @param tid a transaction id
@@ -61,9 +87,9 @@
 
     def load(self, oid, version=""):
         if version:
-            triple = self.version.get(oid)
-            if triple is not None:
-                stored_version, data, serial = triple
+            t = self.version.get(oid)
+            if t is not None:
+                stored_version, data, serial, tid = t
                 if version == stored_version:
                     return data, serial
         return self.current.get(oid)
@@ -89,10 +115,10 @@
     # @defreturn string or None
 
     def modifiedInVersion(self, oid):
-        pair = self.version.get(oid)
-        if pair is None:
+        t = self.version.get(oid)
+        if t is None:
             return None
-        return pair[0]
+        return t[0]
 
     ##
     # Store a new data record in the cache.
@@ -111,10 +137,12 @@
         if version:
             if end_tid is not None:
                 raise ValueError("cache only stores current version data")
-            self.version[oid] = version, data, serial
+            self.version[oid] = version, data, serial, start_tid
             return
         # XXX If there was a previous revision, we need to invalidate it.
         if end_tid is None:
+            if oid in self.current:
+                raise ValueError("already have current data for oid")
             self.current[oid] = data, serial
             self.current_tid[oid] = start_tid
         else:
@@ -127,7 +155,7 @@
     # current data for oid, do nothing.
     # @param oid object id
     # @param version name of version to invalidate.
-    # @param tid the id of the transaction that wrote a now revision of oid
+    # @param tid the id of the transaction that wrote a new revision of oid
 
     def invalidate(self, oid, version, tid):
         if tid > self.tid:
@@ -142,3 +170,14 @@
         start_tid = self.current_tid.pop(oid)
         L = self.noncurrent.setdefault(oid, [])
         L.append((start_tid, tid, data[0], data[1]))
+
+    ##
+    # An iterator yielding the current contents of the cache.
+    # @defreturn iterator
+    # @return oid, version, serial number triples
+
+    def contents(self):
+        for oid, (data, serial) in self.current.items():
+            yield oid, "", serial
+        for oid, (version, data, serial, start_tid) in self.version.items():
+            yield oid, version, serial