Merge ZEO2-branch to trunk.

doc/ZEO/ClientStorage.txt

@@ -10,20 +10,23 @@ ClientStorage
 
   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 requires at leats one argument, the address or
+    addresses of the server(s) to use.  It accepts several other
+    optional keyword arguments.
 
-    The ClientStorage constructor provides a number of additional
-    options (arguments). The full list of arguments is:
+    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
 
-    connection -- Connection information.
+    If a sequence of addresses is specified, the client will use the
+    first server from the list that it can connect to.
 
-     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.
+    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.  
 
@@ -33,7 +36,9 @@ ClientStorage
       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.
+      The default is 20,000,000.  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.
 
@@ -54,10 +59,6 @@ ClientStorage
 
       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__. 
@@ -82,6 +83,13 @@ ClientStorage
 
       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.
+    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.

doc/ZEO/NonZopeREADME.txt

 Zope Enterprize Objects
 
-  ZEO 1.0 requires Python 2.0 when used without Zope.  It depends on
-  versions of asyncore and cPickle that were first released with
-  Python 2.0.
+  Installation
 
-  Put the ZEO package in a directory on your Python path.  On a Unix
-  system, you can use the site-packages directory of your Python lib
-  directory.  The ZEO package is the directory named ZEO that contains
-  an __init__.py file.
+    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.
 
-  Starting (and configuring) the ZEO Server
+    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::
 
-    To start the storage server, run the start.py script contained in
-    the ZEO package.  You can run the script from the package
-    directory or copy it to a directory on your path.
+      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
 
-    Specify the port number when you run the script::
+    To start the storage server, go to your Zope install directory and
+    run::
 
-      python ZEO/start.py -p port_number
+      python lib/python/ZEO/start.py -p port_number
 
-    Or run start.py without arguments to see options.  The options are
-    documented in start.txt.
+    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 the server and client *are* on the same machine, then you can
-    use a Unix domain socket::
+    If they are on the same machine, then you can use a Unix domain
+    socket::
 
-      python ZEO/start.py -U filename
+      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, ZEO.ClientStorage
-      Storage=ZEO.ClientStorage.ClientStorage(('',port_number))
-      db=ZODB.DB(Storage)
+      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
@@ -43,38 +57,24 @@ Zope Enterprize Objects
 
     You can also give the name of a Unix domain socket file::
 
-      import ZODB, ZEO.ClientStorage
-      Storage=ZEO.ClientStorage.ClientStorage(filename)
-      db=ZODB.DB(Storage)
+      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, 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.
 
   Dependencies on other modules
 
-      - The module ThreadedAsync must be on the Python path.
-
-      - The zdaemon module is necessary if you want to run your
-        storage server as a daemon that automatically restarts itself
-        if there is a fatal error.
-
-      - The zLOG module provides a handy logging capability.
-
-      If you are using a version of Python before Python 2:
-
-        - ZServer should be in the Python path, or you should copy the
-          version of asyncore.py from ZServer (from Zope 2.2 or CVS) to
-          your Python path, or you should copy a version of a asyncore
-          from the medusa CVS tree to your Python path. A recent change
-          in asyncore is required.
-
-        - The version of cPickle from Zope, or from the python.org CVS
-          tree must be used. It has a hook to provide control over which
-          "global objects" (e.g. classes) may be pickled.
+    ZEO depends on other modules that are distributed with
+    StandaloneZODB and with Zope.  You can download StandaloneZODB
+    from http://www.zope.org/Products/StandaloneZODB.

doc/ZEO/ZopeREADME.txt

@@ -2,30 +2,38 @@ Zope Enterprise Objects
 
   Installation
 
-    ZEO 1.0 requires Zope 2.2 or higher.
+    ZEO 2.0 requires Zope 2.4 or higher and Python 2.1 or higher.
+    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.
 
-    Put this package (the ZEO directory, without any wrapping directory
+    Put the package (the ZEO directory, without any wrapping directory
     included in a distribution) in your Zope lib/python.
 
-    If you are using Python 1.5.2, the lib/python/ZODB directory must
-    contain a cPickle.so (Unix) or cPickle.pyd (Windows) file.  In
-    many cases, the Zope installation process will not place this file
-    in the right location.  You may need to copy it from lib/python to
-    lib/python/ZODB.
+    The setup.py script in the top-level ZEO directory can also be
+    used.  Run "python setup.py install --home=ZOPE" where ZOPE is the
+    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.)
+    This run the storage sever under zdaemon.  zdaemon automatically
+    restarts programs that exit unexpectedly.
 
-    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::
+    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
 
@@ -38,10 +46,8 @@ Zope Enterprise Objects
     custom_zodb.py, in your Zope install directory, so that Zope uses a
     ClientStorage::
 
-      import ZEO.ClientStorage
-      Storage=ZEO.ClientStorage.ClientStorage(('',port_number))
-
-    (See the misc/custom_zodb.py for an example.)
+      from ZEO.ClientStorage import ClientStorage
+      Storage = ClientStorage(('', port_number))
 
     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
@@ -49,19 +55,20 @@ Zope Enterprise Objects
 
     You can also give the name of a Unix domain socket file::
 
-      import ZEO.ClientStorage
-      Storage=ZEO.ClientStorage.ClientStorage(filename)
+      from ZEO.ClientStorage import ClientStorage
+      Storage = ClientStorage(filename)
 
     There are a number of configuration options available for the
     ClientStorage. See doc/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, 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:
+    processes with unique caches, use something like::
 
       python z2.py -P8700 ZEO_CLIENT=8700
       python z2.py -P8800 ZEO_CLIENT=8800
@@ -74,9 +81,8 @@ Zope Enterprise Objects
     different clients have different software installed, the correct
     state of the database is ambiguous.
 
-    Starting in Zope 2.2, Zope will not modify the Zope database
-    during product installation if the environment variable ZEO_CLIENT
-    is set. 
+    Zope will not modify the Zope database during product installation
+    if the environment variable ZEO_CLIENT is set.
 
     Normally, Zope ZEO clients should be run with ZEO_CLIENT set so
     that product initialization is not performed.