ClientStorage

  The ClientStorage is a ZODB storage implementation that provides
  access to data served bt a ZEO server.  To use a ClientStorage,
  create the SlientStorage and configure your application to use
  it. To configure Zope to use a ClientStorage, create the ClientStorage
  and and assign it to the 'Storage' variable in a 'custom_zodb'
  module (typically a Python file, with a '.py' suffix) in the
  instance home of your Zope installation.

  Creating a ClientStorage

    The ClientStorage requires at leats one argument, the address or
    addresses of the server(s) to use.  It accepts several other
    optional keyword arguments.

    The address argument can be one of:

      - a tuple containing hostname and port number

      - a string specifying the path to a Unix domain socket

      - a sequence of the previous two

    If a sequence of addresses is specified, the client will use the
    first server from the list that it can connect to, subject to the
    constraints imposed by the optional read_only and
    read_only_fallback keyword arguments.

    The ClientStorage constructor provides a number of additional
    options (arguments). The full list of arguments is:

    storage -- The name of the storage to connect to.  

      A ZEO storage server can serve multiple storages.  Each
      storage has a name, which is configured on the server.  The
      server adminstrator should be able to provide this name. The
      default name for both the server and client is '1'.

    cache_size -- The number of bytes to allow for the client cache.
      The default is 20MB.  A large cache can significantly
      increase the performance of a ZEO system.  For applications that
      have a large database, the default size may be too small.

      For more information on client caches, see ClientCache.txt.

    name -- The name to use for the storage. This will be shown in
      Zope's control panel. The default name is a representation of
      the connection information.

    client -- The name to be used for the persistent client cache files.

      This parameter can be used instead of or to override the
      ZEO_CLIENT environment variable. It is generally better to use
      the environment variable because it's easier to change
      environment variables that it is to change Python code for
      creating the storage.

      Also note that, if you are using Zope, the ZEO_CLIENT
      environment variable effects whether products are initialized.

      For more information on client cache files, see ClientCache.txt.

    var -- The directory in which persistent cache files should be
      written. If this option is provided, it is unnecessary to 
      set INSTANCE_HOME in __builtins__. 

      For more information on client cache files, see ClientCache.txt.

    min_disconnect_poll -- The minimum number of seconds to wait before
      retrying connections after connection failure.

      When trying to make a connection, if the connection fails, the
      ZEO client will wait a period of time before retrying the
      connection.  The amount of time waited starts at the value given
      by 'min_disconnect_poll' and doubles on each attempt, but never
      exceeds the number of seconds given by 'max_disconnect_poll'.

      The default is 5 seconds.

    max_disconnect_poll  -- The maximum number of seconds to wait before
      retrying connections after connection failure.

      See min_disconnect_poll.

      The default is 300 seconds.

    wait -- Indicate whether the ClientStorage should block waiting
      for a storage server connection, or whether it should proceed,
      satisfying reads from the client cache. 

    read_only -- Open a read-only connection to the server.  If the
      client attempts to commit a transaction, it will get a
      ReadOnlyError exception.

      Each storage served by a ZEO server can be configured as either
      read-write or read-only.

    read_only_fallback -- A flag indicating whether a read-only
      remote storage should be acceptable as a fallback when no
      writable storages are available.  Defaults to false.  At most
      one of read_only and read_only_fallback should be true.
