[Zodb-checkins] CVS: ZEO/docs - ClientStorage.txt:1.2 NonZopeREADME.txt:1.4 ZopeREADME.txt:1.5
Jeremy Hylton
jeremy@zope.com
Tue, 11 Jun 2002 09:43:07 -0400
Update of /cvs-repository/ZEO/docs
In directory cvs.zope.org:/tmp/cvs-serv5548/docs
Modified Files:
ClientStorage.txt NonZopeREADME.txt ZopeREADME.txt
Log Message:
Merge ZEO2-branch to trunk.
=== ZEO/docs/ClientStorage.txt 1.1 => 1.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.
=== ZEO/docs/NonZopeREADME.txt 1.3 => 1.4 ===
- 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.
-
- 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.
+ Installation
- Starting (and configuring) the ZEO Server
+ 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.
- 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.
+ 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 lib/python/ZEO/start.py -U filename
- 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 @@
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.
=== ZEO/docs/ZopeREADME.txt 1.4 => 1.5 ===
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 @@
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 @@
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 @@
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.