================
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 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 in a single file, of the specified size.

The life of the cache is as follows:

- 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, as transactions commit
  locally, and as data are loaded from the server.

- 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.

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.

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::

    client-storage.zec

where:

client -- the client name, as given by the ClientStorage's ``client``
          argument

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".
