documented client cache contract

src/ZEO/interfaces.py

@@ -21,6 +21,71 @@ class StaleCache(object):
     def __init__(self, storage):
         self.storage = storage
 
+class IClientCache(zope.interface.Interface):
+    """Client cache interface.
+
+    Note that caches need not be thread safe.
+    """
+
+    def close():
+        """Close the cache
+        """
+
+    def load(oid):
+        """Get current data for object
+
+        Returns data and serial, or None.
+        """
+
+    def store(oid, start_tid, end_tid, data):
+        """Store data for the object
+
+        The start_tid is the transaction that committed this data.
+
+        The end_tid is the tid of the next transaction that modified
+        the objects, or None if this is the current version.
+        """
+
+    def loadBefore(oid, tid):
+        """Load the data for the object last modified before the tid
+
+        Returns the data, and start and end tids.
+        """
+
+    def invalidate(oid, tid):
+        """Invalidate data for the object
+
+        If ``tid`` is None, forget all knowledge of `oid`.  (``tid``
+        can be None only for invalidations generated by startup cache
+        verification.)
+
+        If ``tid`` isn't None, and we had current data for ``oid``,
+        stop believing we have current data, and mark the data we had
+        as being valid only up to `tid`.  In all other cases, do
+        nothing.
+        """
+
+    def getLastTid():
+        """Get the last tid seen by the cache
+
+        This is the cached last tid we've seen from the server.
+        """
+
+    def setLastTid(tid):
+        """Save the last tid sent by the server
+        """
+
+    def clear():
+        """Clear/empty the cache
+        """
+
+    def contents():
+        """Return an [oid, tid] iterator over the (current) cache contents
+
+        This is used by cache verification, which has been found to be
+        a bad idea.
+        """
+
 class IServeable(zope.interface.Interface):
     """Interface provided by storages that can be served by ZEO
     """