[Zodb-checkins] CVS: StandaloneZODB/Doc - storage.tex:1.1

[Jeremy Hylton]

Update of /cvs-repository/StandaloneZODB/Doc
In directory cvs.zope.org:/tmp/cvs-serv5413/Doc

Added Files:
	storage.tex 
Log Message:
some preliminary steps towards an official storage api doc


=== Added File StandaloneZODB/Doc/storage.tex ===
% Complete documentation on the extended LaTeX markup used for Python
% documentation is available in ``Documenting Python'', which is part
% of the standard documentation for Python.  It may be found online
% at:
%
%     http://www.python.org/doc/current/doc/doc.html

\documentclass{howto}

%  This is a template for short or medium-size Python-related documents, 
% mostly notably the series of HOWTOs, but it can be used for any
% document you like.   

% The title should be descriptive enough for people to be able to find
% the relevant document. 
\title{ZODB Storage API}

% Increment the release number whenever significant changes are made.
% The author and/or editor can define 'significant' however they like.
\release{1.00}

% At minimum, give your name and an email address.  You can include a
% snail-mail address if you like.
\author{Jeremy Hylton}
\authoraddress{jeremy@zope.com}

\begin{document}
\maketitle

% This makes the Abstract go on a separate page in the HTML version;
% if a copyright notice is used, it should go immediately after this.
%
\ifhtml
\chapter*{Front Matter\label{front}}
\fi

% Copyright statement should go here, if needed.
% ...

% The abstract should be a paragraph or two long, and describe the
% scope of the document.
\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

Spammifying sprockets from Python is both fun and entertaining.
Applying the techniques described here, you can also fill your hard
disk quite effectively.

\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.

Versions.

The various exceptions that can be raised.

\begin{classdesc}{Storage}{}
  
  An object that implements the storage interface must support the
  following methods.

\begin{funcdesc}{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{funcdesc}

\begin{funcdesc}{store}{oid, serial, data, version, transaction}
  
  Store \var{data}, a Python pickle, for the object id, \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 oid, 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.
  \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{funcdesc}

\begin{funcdesc}{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{funcdesc}

\end{classdesc}

\section{ZODB.BaseStorage implementation}

\section{Notes for storage implementors}

\section{Distributed storage interface}

\end{document}