[Zodb-checkins] CVS: ZEO/doc - ClientCache.txt:1.1.2.1 ClientStorage.txt:1.1.2.1 NonZopeREADME.txt:1.1.2.1 ZopeREADME.txt:1.1.2.3

[Jeremy Hylton]

Update of /cvs-repository/ZEO/doc
In directory cvs.zope.org:/tmp/cvs-serv28633/doc

Modified Files:
      Tag: ZEO2-branch
	ZopeREADME.txt 
Added Files:
      Tag: ZEO2-branch
	ClientCache.txt ClientStorage.txt NonZopeREADME.txt 
Log Message:
Add copies of files from ZEO/docs on the trunk.

Update ZopeREADME and NonZopeREADME to be consistent in their
explanations.  Add brief explanation of test.py.


=== Added File ZEO/doc/ClientCache.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 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 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 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.

  - Cache records are written to the cache file, either as
    transactions commit locally, or 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.

  - Cache records are written to the new current cache file, either as
    transactions commit locally, or as data are loaded from the
    server.

  - 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

  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. 

  For example, the second cache file for storage 'spam' and client 8881
  would be named 'cspam-8881-1.zec'.


=== Added File ZEO/doc/ClientStorage.txt ===
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

    At a minimum, a client storage requires an argument (named
    connection) giving connection information. This argument should be
    a string, specifying a unix-domain socket file name, or a tuple
    consisting of a host and port. The host should be a string host
    name or IP number. The port should be a numeric port number.

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

    connection -- Connection information.

     This argument is either a string containing a socket file name
     or a tuple consisting of a string host name or ip number and an
     integer port.

    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 20,000,000.

      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.

    debug -- If this is provided, it should be a non-empty string. It
      indicates that client should log tracing and debugging
      information, using zLOG.

    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_for_server_on_starup -- Indicate whether the ClientStorage
      should block waiting for a storage server connection, or whether
      it should proceed, satisfying reads from the client cache.


=== Added File ZEO/doc/NonZopeREADME.txt ===
Zope Enterprize Objects

  Installation

    ZEO 2.0 requires Python 2.1 or higher when used without Zope.  If
    you use Python 2.1, we recommend the latest minor release (2.1.3 as
    of this writing) because it includes a few bug fixes that affect
    ZEO.

    ZEO is packaged with distutils.  To install it, run this command
    from the top-level ZEO directory::

      python setup.py install

    The setup script will install the ZEO package in your Python
    site-packages directory.

    You can test ZEO before installing it with the test script::

      python test.py -v

    Run the script with the -h option for a full list of options.  The
    ZEO 2.0a1 release contains 87 unit tests on Unix.

  Starting (and configuring) the ZEO Server

    To start the storage server, go to your Zope install directory and
    run::

      python lib/python/ZEO/start.py -p port_number

    This run the storage sever under zdaemon.  zdaemon automatically
    restarts programs that exit unexpectedly.

    The server and the client don't have to be on the same machine.
    If they are on the same machine, then you can use a Unix domain
    socket::

      python lib/python/ZEO/start.py -U filename

    The start script provides a number of options not documented here.
    See doc/start.txt for more information.

  Running a ZEO client

    In your application, create a ClientStorage, rather than, say, a
    FileStorage:

      import ZODB
      from ZEO.ClientStorage import ClientStorage
      Storage = ClientStorage(('', port_number))
      db = ZODB.DB(Storage)

    You can specify a host name (rather than '') if you want.  The port
    number is, of course, the port number used to start the storage
    server.

    You can also give the name of a Unix domain socket file::

      import ZODB
      from ZEO.ClientStorage import ClientStorage
      Storage = ClientStorage(filename)
      db = ZODB.DB(Storage)

    There are a number of configuration options available for the
    ClientStorage. See ClientStorage.txt for details.

    If you want a persistent client cache which retains cache contents
    across ClientStorage restarts, you need to define the environment
    variable, ZEO_CLIENT, or set the client keyword argument to the
    constructor to a unique name for the client.  This is needed so
    that unique cache name files can be computed.  Otherwise, the
    client cache is stored in temporary files which are removed when
    the ClientStorage shuts down.

  Dependencies on other modules

    ZEO depends on other modules that are distributed with
    StandaloneZODB and with Zope.  You can download StandaloneZODB
    from http://www.zope.org/Products/StandaloneZODB.


=== ZEO/doc/ZopeREADME.txt 1.1.2.2 => 1.1.2.3 ===
     top-level Zope directory.
 
+    You can test ZEO before installing it with the test script::
+
+      python test.py -v
+
+    Run the script with the -h option for a full list of options.  The
+    ZEO 2.0a1 release contains 87 unit tests on Unix.
+
   Starting (and configuring) the ZEO Server
 
-    To start the storage server, go to your Zope install directory and::
+    To start the storage server, go to your Zope install directory and
+    run::
 
       python lib/python/ZEO/start.py -p port_number
 
-    (Run start without arguments to see options.)
-
-    Of course, the server and the client don't have to be on the same
-    machine.
+    This run the storage sever under zdaemon.  zdaemon automatically
+    restarts programs that exit unexpectedly.
 
-    If the server and client *are* on the same machine, then you can use 
-    a Unix domain socket::
+    The server and the client don't have to be on the same machine.
+    If they are on the same machine, then you can use a Unix domain
+    socket::
 
       python lib/python/ZEO/start.py -U filename
 
@@ -56,9 +63,10 @@
 
     If you want a persistent client cache which retains cache contents
     across ClientStorage restarts, you need to define the environment
-    variable, ZEO_CLIENT, to a unique name for the client.  This is
-    needed so that unique cache name files can be computed.  Otherwise,
-    the client cache is stored in temporary files which are removed when
+    variable, ZEO_CLIENT, or set the client keyword argument to the
+    constructor to a unique name for the client.  This is needed so
+    that unique cache name files can be computed.  Otherwise, the
+    client cache is stored in temporary files which are removed when
     the ClientStorage shuts down.  For example, to start two Zope
     processes with unique caches, use something like::