[Zodb-checkins] CVS: ZEO/doc - ClientStorage.txt:1.1.2.2

[Jeremy Hylton]

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

Modified Files:
      Tag: ZEO2-branch
	ClientStorage.txt 
Log Message:
Update description of keyword args to ClientStorage


=== ZEO/doc/ClientStorage.txt 1.1.2.1 => 1.1.2.2 ===
   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
 
-    connection -- Connection information.
+      - a string specifying the path to a Unix domain socket
 
-     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.
+      - 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.
+
+    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 @@
       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 @@
 
       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 @@
 
       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.