[Zodb-checkins] CVS: StandaloneZODB/ZEO/doc - ClientCache.txt:1.2.2.1 ClientStorage.txt:1.2.2.1 start.txt:1.2.2.1

[Jeremy Hylton]

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

Added Files:
      Tag: Standby-branch
	ClientCache.txt ClientStorage.txt start.txt 
Log Message:
Merge ZEO-ZRPC-Dev branch into Standby-branch.



=== Added File StandaloneZODB/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 StandaloneZODB/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 StandaloneZODB/ZEO/doc/start.txt ===
The ZEO Server start script, start.py

  ZEO provides a Python script for starting the ZEO server.  The ZEO
  server is implemented as a Python class and could be used with other
  main programs, however, a simple ZEO server is provided for convenience.

  Basic usage

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

      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.

    If the server and client *are* on the same machine, then you can use 
    a Unix domain socket::

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

  Serving custom storages or multiple storages with the storage server

    The Storage server can host multiple storages and can
    host any kind of storage. Each storage has a unique storage
    name.  By default, the ZEO start.py script serves a 
    standard FileStorage with the name '1'.

    You can control what storages are served by creating a Python
    file containing definitions for the storages and using the '-S'
    option to the start.py script to indicate the storage
    to be served. The form of the -S option is::

       -Sstorage_name=module_path:attribute_name

    Where:

	storage_name -- is the storage name used in the ZEO protocol.
	   This is the name that you give as the optional
	   'storage' keyword argument to the ClientStorage constructor.

	module_path -- This is the path to a Python module
	   that defines the storage object(s) to be served.
	   The module path should ommit the prefix (e.g. '.py').

	attribute_name -- This is the name to which the storage object
	  is assigned in the module.


    Consider the following example. I want to serve a FileStorage
    in read-only mode, which I define in the module file 
    /stores/fs.py::

      import ZODB.FileStorage
      Storage=FileStorage.FileStorage('/stores/fs1.fs', read_only=1)

    I then start start.py with the argument::

      python lib/python/ZEO/start.py -U /xxx/var/zeo.sock \
        -S 1=/stores/fs:Storage

    This option says to serve storage '1'. Storage '1' is
    found in attribute 'Storage' from the module
    '/stores/fs'.

    Now consider a more complicated example. I want to serve the storage
    from the previous example. I also want to serve two Oracle
    storages that are defined in the file '/stores/oracle.py'::

      import DCOracle, DCOracleStorage
      system=DCOracleStorage.DCOracleStorage(
        lambda : DCOracle.Connect('system/manager@spamservice')
        )
      scott=DCOracleStorage.DCOracleStorage(
        lambda : DCOracle.Connect('scott/tiger@spamservice')
        )

    I simply need to include three -S options::

      python lib/python/ZEO/start.py -U /xxx/var/zeo.sock \
        -Ssystem=/stores/oracle:system                 \
        -Sscott=/stores/oracle:scott                   \
        -S1=/stores/fs:Storage

    In this case, we made the storage and attribute name the
    same. To connect to the 'system' or 'scott' storage, we
    need to specify the storage in the ClientStorage constructor, as
    in::

      import ZEO.ClientStorage
      Storage=ZEO.ClientStorage.ClientStorage(
          '/xxx/var/zeo.sock', storage='scott')

  Options

    The ZEO server start script is run with one or more command line
    options. An optional FileStorage file name may be provided after the
    options. The options are as follows:

     -D -- Run in debug mode

	In debug mode, the process is not run in the background
	and detailed debugging information is logged. 

	Note that to actually log this information, you need to
	configure logging to include very low-severity (< -300) log
	entries. For example, to configure the stupid logger to log
	these messages, set the environment veriable
	'STUPID_LOG_SEVERITY' to -999.

     -U -- Unix-domain socket file to listen on

	If you want to accept connections on a Unix domain socket, then
	use this option to specify the socket file name.

     -u username or uid number

       The username to run the ZEO server as. You may want to run
       the ZEO server as 'zope' or some other user with limited
       resouces. The only works under Unix, and if ZServer is
       started by root.

       If the server *is* started as root, the 'nobody' user if this
       option isn't used.

     -p port -- port to listen on

       Use this option together with the '-h' option to specify a host
       and port to listen on.

     -h adddress -- host address to listen on

       Use this option together with the '-p' option to specify a host
       and port to listen on.

     -s -- Don't use zdeamon

       This option has no effect on Unix.

     -S storage_name=module_path:attr_name -- A storage specification

	where:

	  storage_name -- is the storage name used in the ZEO protocol.
	     This is the name that you give as the optional
	     'storage' keyword argument to the ClientStorage constructor.

	  module_path -- This is the path to a Python module
	     that defines the storage object(s) to be served.
	     The module path should ommit the prefix (e.g. '.py').

	  attr_name -- This is the name to which the storage object
	    is assigned in the module.