Merge rev 37352 from 3.4 branch.

Massive rewrite of cache.txt, to match current reality.

doc/ZEO/cache.txt

 ZEO Client Cache
 
-  The Client cache provides a disk based cache for each ZEO client.
-  The client cache allows reads to be done from local disk rather than
-  by remote access to the storage server.
+  The client cache provides a disk based cache for each ZEO client.  The
+  client cache allows reads to be done from local disk rather than by remote
+  access to the storage server.
 
-  The cache may be persistent or transient. If the cache is
-  persistent, then the cache files are retained for use after process
-  restarts. A non-persistent cache uses temporary files that are
-  removed when the client storage is closed.
+  The cache may be persistent or transient.  If the cache is persistent, then
+  the cache file is retained for use after process restarts.  A non-
+  persistent cache uses a temporary file.
 
-  The client cache is managed as two files. The cache manager
-  endeavors to maintain the two files at sizes less than or equal to
-  one half the cache size.  One of the cache files is designated the
-  "current" cache file. The other cache file is designated the "old"
-  cache file, if it exists.  All writes are done to the current cache
-  files.  When transactions are committed on the client, transactions
-  are not split between cache files. Large transactions may cause
-  cache files to be larger than one half the target cache size.
+  The client cache is managed in a single file, of the specified size.
 
   The life of the cache is as follows:
 
-  - When the cache is created, the first of the two cache files is
-    created and designated the "current" cache file.
+ -  The cache file is opened (if it already exists), or created and set to
+    the specified size.
 
-  - Cache records are written to the cache file, either as
-    transactions commit locally, or as data are loaded from the
-    server.
+  - Cache records are written to the cache file, as transactions commit
+    locally, and as data are loaded from the server.
 
-  - When the cache file size exceeds one half the cache size, the
-    second cache file is created and designated the "current" cache
-    file.  The first cache file becomes the "old" cache file.
+  - Writes are to "the current file position".  This is a pointer that
+    travels around the file, circularly.  After a record is written, the
+    pointer advances to just beyond it.  Objects starting at the current
+    file position are evicted, as needed, to make room for the next record
+    written.
 
-  - Cache records are written to the new current cache file, either as
-    transactions commit locally, or as data are loaded from the
-    server.
+  A distinct index file is not created, although indexing structures are
+  maintained in memory while a ClientStorage is running.  When a persistent
+  client cache file is reopened, these indexing structures are recreated
+  by analyzing the file contents.
 
-  - When a cache hit is found in the old cache file, it is copied to
-    the current cache file.
+  Persistent cache files are created in the directory named in the ``var``
+  argument to the ClientStorage, or if ``var`` is None, in the current
+  working directory.  Persistent cache files have names of the form::
 
-  - When the current cache file size exceeds one half the cache size, the
-    first cache file is recreated and designated the "current" cache
-    file.  The second cache file becomes the "old" cache file.
-
-  and so on.
-
-  Persistent cache files are created in the directory named in the
-  'var' argument to the ClientStorage (see ClientStorage.txt) or in
-  the 'var' subdirectory of the directory given by the INSTANCE_HOME
-  builtin (created by Zope), or in the current working directory.
-  Persistent cache files have names of the form::
-
-    cstorage-client-n.zec
+    client-storage.zec
 
   where:
 
-    storage -- the storage name
-
-    client -- the client name, as given by the 'ZEO_CLIENT' environment
-      variable or the 'client' argument provided when creating a client
-      storage.
-
-    n -- '0' for the first cache file and '1' for the second. 
+    client -- the client name, as given by the ClientStorage's ``client``
+              argument
 
-  For example, the second cache file for storage 'spam' and client 8881
-  would be named 'cspam-8881-1.zec'.
+    storage -- the storage name, as given by the ClientStorage's ``storage``
+               argument; this is typically a string denoting a small integer,
+               "1" by default
 
+  For example, the cache file for client '8881' and storage 'spam' is named
+  "8881-spam.zec".

src/ZEO/cache.py

@@ -16,7 +16,7 @@
 ClientCache exposes an API used by the ZEO client storage.  FileCache stores
 objects on disk using a 2-tuple of oid and tid as key.
 
-ClientCaches API is similar to a storage API with methods like load(),
+ClientCache's API is similar to a storage API, with methods like load(),
 store(), and invalidate().  It manages in-memory data structures that allow
 it to map this richer API onto the simple key-based API of the lower-level
 FileCache.