Commit ddfed531 authored by Jim Fulton's avatar Jim Fulton

added documentation files

parent 1dd9366a
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'.
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.
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.
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'.
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.
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