Skip to content

Z
ZODB
Commit 1f59805f authored by Jeremy Hylton's avatar Jeremy Hylton
Browse files
Options

moved to Releases/ZEO/docs

parent 29f549e2
Hide whitespace changes
Inline Side-by-side
Showing with 0 additions and 463 deletions
src/ZEO/doc/ClientCache.txt deleted 100644 → 0
View file @ 29f549e2
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'.
src/ZEO/doc/ClientStorage.txt deleted 100644 → 0
View file @ 29f549e2
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.
src/ZEO/doc/NonZopeREADME.txt deleted 100644 → 0
View file @ 29f549e2
Zope Enterprize Objects
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.
Starting (and configuring) the ZEO Server
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.
Specify the port number when you run the script::
python ZEO/start.py -p port_number
Or run start.py without arguments to see options. The options are
documented in start.txt.
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 ZEO/start.py -U filename
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)
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, ZEO.ClientStorage
Storage=ZEO.ClientStorage.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
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.
src/ZEO/doc/ZopeREADME.txt deleted 100644 → 0
View file @ 29f549e2
Zope Enterprise Objects
Put this package (the ZEO directory, without any wrapping directory
included in a distribution) in your Zope lib/python.
Starting (and configuring) the ZEO Server
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
The start script provides a number of options not documented here.
See doc/start.txt for more information.
Running Zope as a ZEO client
To get Zope to use the server, create a custom_zodb module,
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.)
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 ZEO.ClientStorage
Storage=ZEO.ClientStorage.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
the ClientStorage shuts down. For example, to start two Zope
processes with unique caches, use something like:
python z2.py -P8700 ZEO_CLIENT=8700
python z2.py -P8800 ZEO_CLIENT=8800
Zope product installation
Normally, Zope updates the Zope database during startup to reflect
product changes or new products found. It makes no sense for
multiple ZEO clients to do the same installation. Further, if
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.
Normally, Zope ZEO clients should be run with ZEO_CLIENT set so
that product initialization is not performed.
If you do install new Zope products, then you need to take a
special step to cause the new products to be properly registered
in the database. The easiest way to do this is to start Zope
once with the environment variable FORCE_PRODUCT_LOAD set.
The interaction between ZEO and Zope product installation is
unfortunate. In the future, this interaction will be removed by
src/ZEO/doc/start.txt deleted 100644 → 0
View file @ 29f549e2
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.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7