[Zope-CVS] CVS: ZODB/doc - zdctl.txt:1.1 storage.tex:1.1
README.txt:1.1 Makefile:1.1 ACKS:1.1
Jeremy Hylton
jeremy at zope.com
Wed Feb 11 17:13:41 EST 2004
Update of /cvs-repository/ZODB/doc
In directory cvs.zope.org:/tmp/cvs-serv1866
Added Files:
zdctl.txt storage.tex README.txt Makefile ACKS
Log Message:
Copy a bunch of files from the ZODB3/Doc directory, losing history.
=== Added File ZODB/doc/zdctl.txt ===
Using zdctl and zdrun to manage server processes
================================================
Summary
-------
Starting with Zope 2.7 and ZODB 3.2, Zope has a new way to configure
and control server processes. This file documents the new approach to
server process management; the new approach to configuration is
documented elsewhere, although some examples will be given here. We
use the ZEO server as a running example, although this isn't a
complete manual for configuring or running ZEO.
This documentation applies to Unix/Linux systems; zdctl and zdrun do
not work on Windows.
Prerequisites
-------------
This document assumes that you have installed the ZODB3 software
(version 3.2 or higher) using a variation on the following command,
given from the root directory of the ZODB3 distribution::
$ python setup.py install
This installs the packages ZConfig, ZEO, zdaemon, zLOG, ZODB and
various other needed packages and extension modules in the Python
interpreter's site-packages directory, and installs scripts including
zdctl.py, zdrun.py, runzeo.py and mkzeoinst.py in /usr/local/bin
(actually the bin directory from which the python interpreter was
loaded).
When you receive ZODB as a part of Zope (version 2.7 or higher), the
installation instructions will explain how to reach a similar state.
Introduction
------------
The most basic way to run a ZEO server is using the following
command::
$ runzeo.py -a 9999 -f Data.fs
Here 9999 is the ZEO port (you can pick your own unused TCP port
number in the range 1024 through 65535, inclusive); Data.fs is the
storage file. Again, you can pick any filename you want; the
ZODB.FileStorage module code creates this file and various other files
with additional extensions, like Data.fs.index, Data.fs.lock, and
Data.fs.tmp.
If something's wrong, for example if you picked a bad port number or
filename, you'll get an error message or an exception right away and
runzeo.py will exit with a non-zero exit status. The exit status is 2
for command line syntax errors, 1 for other errors.
If all's well, runzeo.py will emit a few logging messages to stderr
and start serving, until you hit ^C. For example::
$ runzeo.py -a 9999 -f Data.fs
------
2003-01-24T11:49:27 INFO(0) RUNSVR opening storage '1' using FileStorage
------
2003-01-24T11:49:27 INFO(0) ZSS:23531 StorageServer created RW with
storages: 1:RW:Data.fs
------
2003-01-24T11:49:27 INFO(0) zrpc:23531 listening on ('', 9999)
At this point you can hit ^C to stop it; runzeo.py will catch the
interrupt signal, emit a few more log messages and exit::
^C
------
2003-01-24T12:11:15 INFO(0) RUNSVR terminated by SIGINT
------
2003-01-24T12:11:15 INFO(0) RUNSVR closing storage '1'
$
This may be fine for testing, but a bad idea for running a ZEO server
in a production environment. In production, you want the ZEO server
to be run as a daemon process, you want the log output to go to a
file, you want the ZEO server to be started when the system is
rebooted, and (usually) you want the ZEO server to be automatically
restarted when it crashes. You should also have a log rotation policy
in place so that your disk doesn't fill up with log messages.
The zdctl/zdrun combo can take care of running a server as a daemon
process and restarting it when it crashes. It can also be used to
start it when the system is rebooted. Sending log output to a file is
done by adjusting the ZEO server configuration. There are many fine
existing tools to rotate log files, so we don't provide this
functionality; zdctl has a command to send the server process a
SIGUSR2 signal to tell it to reopen its log file after log rotation
has taken place (the ZEO server has a signal handler that catches
SIGUSR2 for this purpose).
In addition, zdctl lets a system administrator or developer control
the server process. This is useful to deal with typical problems like
restarting a hanging server or adjusting a server's configuration.
The zdctl program can be used in two ways: in one-shot mode it
executes a single command (such as "start", "stop" or "restart"); in
interactive mode it acts much like a typical Unix shell or the Python
interpreter, printing a prompt to standard output and reading commands
from standard input. It currently cannot be used to read commands
from a file; if you need to script it, you can use a shell script
containing repeated one-shot invocations.
zdctl can be configured using command line options or a configuration
file. In practice, you'll want to use a configuration file; but first
we'll show some examples using command line options only. Here's a
one-shot zdctl command to start the ZEO server::
$ zdctl.py -p "runzeo.py -a 9999 -f Data.fs" start
The -p option specifies the server program; it is the runzeo
invocation that we showed before. The start argument tells it to
start the process. What actually happens is that zdctl starts zdrun,
and zdrun now manages the ZEO server process. The zdctl process exits
once zdrun has started the ZEO server process; the zdrun process stays
around, and when the ZEO server process crashes it will restart it.
To check that the ZEO server is now running, use the zdctl status
command::
$ zdctl.py -p "runzeo.py -a 9999 -f Data.fs" status
This prints a one-line message telling you that the program is
running. To stop the ZEO server, use the zdctl stop command::
$ zdctl.py -p "runzeo.py -a 9999 -f Data.fs" stop
To check that is no longer running, use the zdctl status command
again.
Daemon mode
-----------
If you are playing along on your computer, you cannot have missed that
some log output has been spewing to your terminal window. While this
may give you a warm and fuzzy feeling that something is actually
happening, after a whiile it can get quite annoying (especially if
clients are actually connecting to the server). This can be avoided
by using the -d flag, which enables "daemon mode"::
$ zdctl.py -d -p "runzeo.py -a 9999 -f Data.fs" start
Daemon mode does several subtle things; see for example section 13.3
of "Advanced Programming in the UNIX Environment" by Richard Stevens
for a good explanation of daemon mode. For now, the most important
effect is that the standard input, output and error streams are
redirected to /dev/null, and that the process is "detached" from your
controlling tty, which implies that it won't receive a SIGHUP signal
when you log out.
Using a configuration file
--------------------------
I hope you are using a Unix shell with command line history, otherwise
entering the examples above would have been quite a pain. But a
better way to control zdctl and zdrun's many options without having to
type them over and over again is to use a configuration file. Here's
a small configuration file; place this in the file "zeoctl.conf" (the
name is just a convention; you can call it "foo" if you prefer)::
# Sample zdctl/zdrun configuration
<runner>
program runzeo.py -a 9999 -f Data.fs
daemon true
directory /tmp/zeohome
socket-name /tmp/zeohome/zdsock
</runner>
The "program" and "daemon" lines correspond to the -p and -d command
line options discussed above. The "directory" line is new. It
specifies a directory into which zdrun (but not zdctl!) chdirs. This
directory should exist; zdctl won't create it for you. The Data.fs
filename passed to runzeo.py is interpreted relative to this
directory. Finally, the "socket-name" line names the Unix domain
socket that is used for communication between zdctl and zdrun. It
defaults to zdsock in the current directory, a default you definitely
want to override for production usage.
To invoke zdctl with a configuration file, use its -C option to name
the configuration file, for example::
$ zdctl.py -C zeoctl.conf start
$ zdctl.py -C zeoctl.conf status
$ zdctl.py -C zeoctl.conf stop
Interactive mode
----------------
Using a configuration file makes it a little easier to repeatedly
start, stop and request status of a particular server, but it still
requires typing the configuration file name on each command.
Fortunately, zdctl.py can be used as an interactive "shell" which lets
you execute repeated commands for the same server. Simply invoke
zdctl.py without the final argument ("start", "status" or "stop" in
the above examples)::
$ zdctl.py -C zeoctl.conf
program: runzeo.py -a 9999 -f Data.fs
daemon manager not running
zdctl>
The first two lines of output are status messages (and could be
different in your case); the final line is the interactive command
prompt. At this prompt, you can type commands::
zdctl> help
Documented commands (type help <topic>):
========================================
EOF fg foreground help kill
logreopen logtail quit reload restart
shell show start status stop
wait
zdctl> help start
start -- Start the daemon process.
If it is already running, do nothing.
zdctl> start
daemon process started, pid=31580
zdctl> status
program running; pid=31580
zdctl> stop
daemon process stopped
zdctl> quit
daemon manager not running
$
In short, the commands you can type at the interactive prompt are the
same commands (with optional arguments) that you can use as positional
arguments on the zdctl.py command line.
The interactive shell has some additional features:
- Line editing and command line history using the standard GNU
readline module.
- A blank line repeats the last command (especially useful for status).
- Command and argument completion using the TAB key.
One final note: some people don't like it that an invocation without
arguments enters interactive mode. If this describes you, there's an
easy way to disable this feature: add a line saying
default-to-interactive false
to the zeoctl.conf file. You can still enter interactive mode by
using the -i option.
Using mkzeoinst.py
------------------
If you still think that all of the above is a lot of typing, you're
right. Fortunately, there's a simple utility that help you creating
and configuring a ZEO server instance. mkzeoinst.py requires one
argument, the ZEO server's "home directory". After that, you can
optionally specify a service port number; the port defaults to 9999.
mkzeoinst.py creates the server home directory (and its ancestor
directories if necessary), and then creates the following directory
substructure:
bin/ - directory for scripts (zeoctl)
etc/ - directory for configuration files (zeo.conf, zeoctl.conf)
log/ - directory for log files (zeo.log, zeoctl.log)
var/ - directory for data files (Data.fs and friends)
If the server home directory or any of its subdirectories already
exist, mkzeoinst.py will note this and assume you are rebuilding an
existing instance. (In fact, it prints a message for each directory
it creates but is silent about existing directories.)
It then creates the following files:
bin/zeoctl - executable shell script to run zdctl.py
etc/zeo.conf - configuration file for ZEO
etc/zeoctl.conf - configuration file for zdrun.py and zdctl.py
If any of the files it wants to create already exists and is
non-empty, it does not write the file. (An empty file will be
overwritten though.) If the existing contents differ from what it
would have written if the file didn't exist, it prints a warning
message; otherwise the skipping is silent.
Other errors (e.g. permission errors creating or reading files or
directories) cause mkzeoinst.py to bail with an error message; it does
not clean up the work already done.
The created files contain absolute path references to all of the
programs, files, directories used. They also contain default values
for most configuration settings that one might normally want to
configure. Most configured settings are the same as the defaults;
however, daemon mode is on while the regular default is off. Log
files are configured to go into the log directory. If configures
separate log files for zdrun.py/zdctl.py (log/zeoctl.log) and for the
ZEO server itself (log/zeo.log). Once created, the files are yours;
feel free to edit them to suit your taste.
The bin/zeoctl script should be invoked with the positional arguments
(e,g, "start", "stop" or "status") that you would pass to zdctl.py;
the script hardcodes the configuration file so you don't have to pass
that. It can also be invoked without arguments to enter interactive
mode.
One final detail: if you want the ZEO server to be started
automatically when the machine is rebooted, and you're lucky enough to
be using a recent Red Hat (or similar) system, you can copy the
bin/zeoctl script into the /etc/rc.d/init.d/ directory and use
chkconfig(8) to create the correct symlinks to it; the bin/zeoctl
script already has the appropriate magical comments for chkconfig.
zdctl reference
---------------
XXX TBD
zdrun reference
---------------
XXX TBD
=== Added File ZODB/doc/storage.tex ===
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Copyright (c) 2001, 2002, 2003 Zope Corporation and Contributors.
% All Rights Reserved.
%
% This software is subject to the provisions of the Zope Public License,
% Version 2.0 (ZPL). A copy of the ZPL should accompany this distribution.
% THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
% WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
% WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
% FOR A PARTICULAR PURPOSE.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\documentclass{howto}
\title{ZODB Storage API}
\release{1.00}
\author{Zope Corporation}
\authoraddress{
Lafayette Technology Center\\
513 Prince Edward Street\\
Fredericksburg, VA 22401\\
\url{http://www.zope.com/}
}
\begin{document}
\maketitle
\begin{abstract}
\noindent
A ZODB storage provides the low-level storage for ZODB transactions.
Examples include FileStorage, OracleStorage, and bsddb3Storage. The
storage API handles storing and retrieving individual objects in a
transaction-specifc way. It also handles operations like pack and
undo. This document describes the interface implemented by storages.
\end{abstract}
\tableofcontents
\section{Concepts}
\subsection{Versions}
Versions provide support for long-running transactions. They extend
transaction semantics, such as atomicity and serializability, to
computation that involves many basic transactions, spread over long
periods of time, which may be minutes, or years.
Versions were motivated by a common problem in website management,
but may be useful in other domains as well. Often, a website must be
changed in such a way that changes, which may require many operations
over a period of time, must not be visible until completed and
approved. Typically this problem is solved through the use of
\dfn{staging servers}. Essentially, two copies of a website are
maintained. Work is performed on a staging server. When work is
completed, the entire site is copied from the staging server to the
production server. This process is too resource intensive and too
monolithic. It is not uncommon for separate unrelated changes to be
made to a website and these changes will need to be copied to the
production server independently. This requires an unreasonable amount
of coordination, or multiple staging servers.
ZODB addresses this problem through long-running transactions, called
\dfn{versions}. Changes made to a website can be made to a version
(of the website). The author sees the version of the site that
reflects the changes, but people working outside of the version cannot
see the changes. When the changes are completed and approved, they
can be saved, making them visible to others, almost instantaneously.
Versions require support from storage managers. Version support is an
optional feature of storage managers and support in a particular
database will depend on support in the underlying storage manager.
\section{Storage Interface}
General issues:
The objects are stored as Python pickles. The pickle format is
important, because various parts of ZODB depend on it, e.g. pack.
Conflict resolution
Various versions of the interface.
Concurrency and transactions.
The various exceptions that can be raised.
An object that implements the \class{Storage} interface must support
the following methods:
\begin{methoddesc}{tpc_begin}{transaction\optional{, tid\optional{,
status}}}
Begin the two-phase commit for \var{transaction}.
This method blocks until the storage is in the not committing state,
and then places the storage in the committing state. If the storage
is in the committing state and the given transaction is the
transaction that is already being committed, then the call does not
block and returns immediately without any effect.
The optional \var{tid} argument specifies the timestamp to be used
for the transaction ID and the new object serial numbers. If it is
not specified, the implementation chooses the timestamp.
The optional \var{status} argument, which has a default value of
\code{'~'}, has something to do with copying transactions.
\end{methoddesc}
\begin{methoddesc}{store}{oid, serial, data, version, transaction}
Store \var{data}, a Python pickle, for the object ID identified by
\var{oid}. A Storage need not and often will not write data
immediately. If data are written, then the storage should be
prepared to undo the write if a transaction is aborted.
The value of \var{serial} is opaque; it should be the value returned
by the \method{load()} call that read the object. \var{version} is
a string that identifies the version or the empty string.
\var{transaction}, an instance of
\class{ZODB.Transaction.Transaction}, is the current transaction.
The current transaction is the transaction passed to the most recent
\method{tpc_begin()} call.
There are several possible return values, depending in part on
whether the storage writes the data immediately. The return value
will be one of:
\begin{itemize}
\item \code{None}, indicating the data has not been stored yet
\item a string, containing the new serial number for the
object
\item a sequence of object ID, serial number pairs, containing the
new serial numbers for objects updated by earlier
\method{store()} calls that are part of this transaction.
If the serial number is not a string, it is an exception
object that should be raised by the caller.
\note{This explanation is confusing; how to tell the
sequence of pairs from the exception? Barry, Jeremy, please
clarify here.}
\end{itemize}
Several different exceptions can be raised when an error occurs.
\begin{itemize}
\item \exception{ConflictError} is raised when \var{serial}
does not match the most recent serial number for object
\var{oid}.
\item \exception{VersionLockError} is raised when object
\var{oid} is locked in a version and the \var{version}
argument contains a different version name or is empty.
\item \exception{StorageTransactionError} is raised when
\var{transaction} does not match the current transaction.
\item \exception{StorageError} or, more often, a subclass of
it, is raised when an internal error occurs while the
storage is handling the \method{store()} call.
\end{itemize}
\end{methoddesc}
\begin{methoddesc}{restore}{oid, serial, data, version, transaction}
A lot like \method{store()} but without all the consistency checks.
This should only be used when we \emph{know} the data is good, hence
the method name. While the signature looks like \method{store()},
there are some differences:
\begin{itemize}
\item \var{serial} is the serial number of this revision, not
of the previous revision. It is used instead of
\code{self._serial}, which is ignored.
\item Nothing is returned.
\item \var{data} can be \code{None}, which indicates a George
Bailey object (one who's creation has been transactionally
undone).
\end{itemize}
\end{methoddesc}
\begin{methoddesc}{new_oid}{}
XXX
\end{methoddesc}
\begin{methoddesc}{tpc_vote}{transaction}
XXX
\end{methoddesc}
\begin{methoddesc}{tpc_finish}{transaction, func}
Finish the transaction, making any transaction changes
permanent. Changes must be made permanent at this point.
If \var{transaction} is not the current transaction, nothing
happens.
\var{func} is called with no arguments while the storage lock is
held, but possibly before the updated date is made durable. This
argument exists to support the \class{Connection} object's
invalidation protocol.
\end{methoddesc}
\begin{methoddesc}{abortVersion}{version, transaction}
Clear any changes made by the given version. \var{version} is the
version to be aborted; it may not be the empty string.
\var{transaction} is the current transaction.
This method is state dependent. It is an error to call this method
if the storage is not committing, or if the given transaction is not
the transaction given in the most recent \method{tpc_begin()}.
If undo is not supported, then version data may be simply
discarded. If undo is supported, however, then the
\method{abortVersion()} operation must be undoable, which implies
that version data must be retained. Use the \method{supportsUndo()}
method to determine if the storage supports the undo operation.
\end{methoddesc}
\begin{methoddesc}{commitVersion}{source, destination, transaction}
Store changes made in the \var{source} version into the
\var{destination} version. A \exception{VersionCommitError} is
raised if the \var{source} and \var{destination} are equal or if
\var{source} is an empty string. The \var{destination} may be an
empty string, in which case the data are saved to non-version
storage.
This method is state dependent. It is an error to call this method
if the storage is not committing, or if the given transaction is not
the transaction given in the most recent \method{tpc_begin()}.
If the storage doesn't support undo, then the old version data may
be discarded. If undo is supported, then this operation must be
undoable and old transaction data may not be discarded. Use the
\method{supportsUndo()} method to determine if the storage supports
the undo operation.
\end{methoddesc}
\begin{methoddesc}{close}{}
Finalize the storage, releasing any external resources. The storage
should not be used after this method is called.
\end{methoddesc}
\begin{methoddesc}{lastSerial}{oid}
Returns the serial number for the last committed transaction for the
object identified by \var{oid}. If there is no serial number for
\var{oid} --- which can only occur if it represents a new object ---
returns \code{None}.
\note{This is not defined for \class{ZODB.BaseStorage}.}
\end{methoddesc}
\begin{methoddesc}{lastTransaction}{}
Return transaction ID for last committed transaction.
\note{This is not defined for \class{ZODB.BaseStorage}.}
\end{methoddesc}
\begin{methoddesc}{getName}{}
Returns the name of the store. The format and interpretation of
this name is storage dependent. It could be a file name, a database
name, etc.
\end{methoddesc}
\begin{methoddesc}{getSize}{}
An approximate size of the database, in bytes.
\end{methoddesc}
\begin{methoddesc}{getSerial}{oid}
Return the serial number of the most recent version of the object
identified by \var{oid}.
\end{methoddesc}
\begin{methoddesc}{load}{oid, version}
Returns the pickle data and serial number for the object identified
by \var{oid} in the version \var{version}.
\end{methoddesc}
\begin{methoddesc}{loadSerial}{oid, serial}
Load a historical version of the object identified by \var{oid}
having serial number \var{serial}.
\end{methoddesc}
\begin{methoddesc}{modifiedInVersion}{oid}
Returns the version that the object with identifier \var{oid} was
modified in, or an empty string if the object was not modified in a
version.
\end{methoddesc}
\begin{methoddesc}{isReadOnly}{}
Returns true if the storage is read-only, otherwise returns false.
\end{methoddesc}
\begin{methoddesc}{supportsTransactionalUndo}{}
Returns true if the storage implementation supports transactional
undo, or false if it does not.
\note{This is not defined for \class{ZODB.BaseStorage}.}
\end{methoddesc}
\begin{methoddesc}{supportsUndo}{}
Returns true if the storage implementation supports undo, or false
if it does not.
\end{methoddesc}
\begin{methoddesc}{supportsVersions}{}
Returns true if the storage implementation supports versions, or
false if it does not.
\end{methoddesc}
\begin{methoddesc}{transactionalUndo}{transaction_id, transaction}
Undo a transaction specified by \var{transaction_id}. This may need
to do conflict resolution.
\note{This is not defined for \class{ZODB.BaseStorage}.}
\end{methoddesc}
\begin{methoddesc}{undo}{transaction_id}
Undo the transaction corresponding to the transaction ID given by
\var{transaction_id}. If the transaction cannot be undone, then
\exception{UndoError} is raised. On success, returns a sequence of
object IDs that were affected.
\end{methoddesc}
\begin{methoddesc}{undoInfo}{XXX}
XXX
\end{methoddesc}
\begin{methoddesc}{undoLog}{\optional{first\optional{,
last\optional{, filter}}}}
Returns a sequence of \class{TransactionDescription} objects for
undoable transactions. \var{first} gives the index of the first
transaction to be retured, with \code{0} (the default) being the
most recent.
\note{\var{last} is confusing; can Barry or Jeremy try to explain
this?}
If \var{filter} is provided and not \code{None}, it must be a
function which accepts a \class{TransactionDescription} object as a
parameter and returns true if the entry should be reported. If
omitted or \code{None}, all entries are reported.
\end{methoddesc}
\begin{methoddesc}{versionEmpty}{version}
Return true if there are no transactions for the specified version.
\end{methoddesc}
\begin{methoddesc}{versions}{\optional{max}}
Return a sequence of the versions stored in the storage. If
\var{max} is given, the implementation may choose not to return more
than \var{max} version names.
\end{methoddesc}
\begin{methoddesc}{history}{oid\optional{, version\optional{,
size\optional{, filter}}}}
Return a sequence of \class{HistoryEntry} objects. The information
provides a log of the changes made to the object. Data are reported
in reverse chronological order. If \var{version} is given, history
information is given with respect to the specified version, or only
the non-versioned changes if the empty string is given. By default,
all changes are reported. The number of history entries reported is
constrained by \var{size}, which defaults to \code{1}. If
\var{filter} is provided and not \code{None}, it must be a function
which accepts a \class{HistoryEntry} object as a parameter and
returns true if the entry should be reported. If omitted or
\code{None}, all entries are reported.
\end{methoddesc}
\begin{methoddesc}{pack}{t, referencesf}
Remove transactions from the database that are no longer needed to
maintain the current state of the database contents. Undo will not
be restore objects to states from before the most recent call to
\method{pack()}.
\end{methoddesc}
\begin{methoddesc}{copyTransactionsFrom}{other\optional{, verbose}}
Copy transactions from another storage, given by \var{other}. This
is typically used when converting a database from one storage
implementation to another. This will use \method{restore()} if
available, but will use \method{store()} if \method{restore()} is
not available. When \method{store()} is needed, this may fail with
\exception{ConflictError} or \exception{VersionLockError}.
\end{methoddesc}
\begin{methoddesc}{iterator}{\optional{start\optional{, stop}}}
Return a iterable object which produces all the transactions from a
range. If \var{start} is given and not \code{None}, transactions
which occurred before the identified transaction are ignored. If
\var{stop} is given and not \code{None}, transactions which occurred
after the identified transaction are ignored; the specific
transaction identified by \var{stop} will be included in the series
of transactions produced by the iterator.
\note{This is not defined for \class{ZODB.BaseStorage}.}
\end{methoddesc}
\begin{methoddesc}{registerDB}{db, limit}
Register a database \var{db} for distributed storage invalidation
messages. The maximum number of objects to invalidate is given by
\var{limit}. If more objects need to be invalidated than this
limit, then all objects are invalidated. This argument may be
\code{None}, in which case no limit is set. Non-distributed
storages should treat this is a null operation. Storages should
work correctly even if this method is not called.
\end{methoddesc}
\section{ZODB.BaseStorage Implementation}
\section{Notes for Storage Implementors}
\section{Distributed Storage Interface}
Distributed storages support use with multiple application processes.
Distributed storages have a storage instance per application and some
sort of central storage server that manages data on behalf of the
individual storage instances.
When a process changes an object, the object must be invaidated in all
other processes using the storage. The central storage sends a
notification message to the other storage instances, which, in turn,
send invalidation messages to their respective databases.
\end{document}
=== Added File ZODB/doc/README.txt ===
ZODB Documentation
==================
Simple text files
-----------------
This is a brief summary of the text documentation included with ZODB.
Most of the text actually uses the restructured text format. The
summary lists the title and path of each document.
BerkeleyDB Storages for ZODB
Doc/BDBStorage.txt
Using zdctl and zdrun to manage server processes
Doc/zdctl.txt
ZEO Client Cache
Doc/ZEO/cache.txt
Running a ZEO Server HOWTO
Doc/ZEO/howto.txt
ZEO Client Cache Tracing
Doc/ZEO/trace.txt
Formatted documents
-------------------
There are two documents written the Python documentation tools.
ZODB/ZEO Programming Guide
PDF: zodb.pdf
HTML: zodb/zodb.html
ZODB Storage API
PDF: storage.pdf
HTML: storage/storage.html
The documents located here can be formatted using the mkhowto script
which is part of the Python documentation tools. The recommended use
of this script is to create a symlink from some handy bin/ directory
to the script, located in Doc/tools/mkhowto in the Python source
distribution; that script will locate the various support files it
needs appropriately.
The Makefile contains the commands to produce both the PDF and HTML
versions of the documents.
=== Added File ZODB/doc/Makefile ===
MKHOWTO=mkhowto
MKHTML=$(MKHOWTO) --html --iconserver=. --split=4 --dvips-safe
ZODBTEX = guide/gfdl.tex guide/introduction.tex guide/modules.tex \
guide/prog-zodb.tex guide/storages.tex guide/transactions.tex \
guide/zeo.tex guide/zodb.tex
default: pdf
all: pdf ps html
pdf: storage.pdf zodb.pdf
ps: storage.ps zodb.ps
html: storage/storage.html zodb/zodb.html
storage.pdf: storage.tex
$(MKHOWTO) --pdf $<
storage.ps: storage.tex
$(MKHOWTO) --ps $<
storage/storage.html: storage.tex
$(MKHTML) storage.tex
zodb.pdf: $(ZODBTEX)
$(MKHOWTO) --pdf guide/zodb.tex
zodb.ps: $(ZODBTEX)
$(MKHOWTO) --ps guide/zodb.tex
zodb/zodb.html: $(ZODBTEX)
$(MKHTML) guide/zodb.tex
clobber:
rm -rf storage.pdf storage.ps storage/ zodb.pdf zodb.ps zodb/
=== Added File ZODB/doc/ACKS ===
Acknowledgments
---------------
This file lists people who have contribute code, bug fixes, ideas, and
other support for ZODB. Alas it is probably not complete.
Anthony Baxter
John Belmonte
Johan Dahlin
Toby Dickenson
Fred L. Drake, Jr.
Casey Duncan
Jon Dyte
Jim Fulton
Florent Guillaume
Shane Hathaway
Nicholas Henke
Jeremy Hylton
Matt Kromer
Andrew Kuchling
Andreas Jung
Brian Lloyd
Ken Manheimer
Dieter Maurer
Chris McDonough
Tim Peters
Chris Petrilli
Christian Reis
Guido van Rossum
Neil Schemenauer
Tres Seaver
Sidnei da Silva
Evan Simpson
Jens Vagelpohl
Greg Ward
Barry Warsaw
Chris Withers
More information about the Zope-CVS
mailing list