DbTxn



NAME

       DbTxn - Db transaction management


SYNOPSIS

       #include <db_cxx.h>

       int
       DbTxn::prepare();

       int
       DbTxn::commit();

       int
       DbTxn::abort();

       u_int32_t
       DbTxn::id();


DESCRIPTION

       The DB library is a family of classes that provides a mod-
       ular programming interface to transactions and record-ori-
       ented  file  access.   The  library  includes  support for
       transactions, locking, logging and file page  caching,  as
       well  as  various  indexed  access  methods.   Many of the
       classes (e.g., the file page  caching  class)  are  useful
       independent of the other DB classes, although some classes
       are explicitly based on other classes (e.g.,  transactions
       and  logging).   For a general description of the DB pack-
       age, see db_intro(3).

       This manual page describes the specific details of the  Db
       transaction  support.  The DbTxn class is used in conjunc-
       tion with DbTxnMgr(3) to  provide  transaction  semantics.
       Full  transaction  support  is provided by a collection of
       modules that provide interfaces to the  services  required
       for  transaction  processing.  These services are recovery
       (see DbLog(3)), concurrency  control  (see  DbLock(3)  and
       DbLockTab(3)), and the management of shared data (see DbM-
       pool(3) and DbMpoolFile(3)).  Transaction semantics can be
       applied  to  the access methods described in Db(3) through
       method call parameters.

       The model intended for transactional use (and that is used
       by the access methods) is that write-ahead logging is pro-
       vided by DbLog(3) to record both before-  and  after-image
       logging.   Locking follows a two-phase protocol (i.e., all
       locks are released at transaction commit).

  DbTxn::prepare
       The DbTxn::prepare method initiates the beginning of a two
       phase  commit.   In a distributed transaction environment,
       db can be used as a local transaction  manager.   In  this
       case,  the  distributed transaction manager must send pre-
       pare messages to each local manager.   The  local  manager
       commit log record is written and flushed to disk,  as  are
       all previously written log records.  If the transaction is
       nested, its locks are acquired by the parent  transaction,
       otherwise  its  locks are released.  Any applications that
       require strict two-phase  locking  must  not  release  any
       locks  explicitly,  leaving  them  all  to  be released by
       DbTxn::commit.

       The  DbTxn::commit  method  throws  a  DbException(3)   or
       returns the value of errno on failure and 0 on success.

  DbTxn::abort
       The  DbTxn::abort method causes an abnormal termination of
       the transaction.  The log is played backwards and any nec-
       essary  recovery  operations  are  initiated  through  the
       recover method specified to DbTxnMgr::open.  After  recov-
       ery  is  completed,  all locks held by the transaction are
       acquired by the parent transaction in the case of a nested
       transaction or released in the case of a non-nested trans-
       action.  As is the case  for  DbTxn::commit,  applications
       that  require  strict two phase locking should not explic-
       itly release any locks.

       The DbTxn::abort method throws a DbException(3) or returns
       the value of errno on failure and 0 on success.

  DbTxn::id
       The  DbTxn::id  method  returns  the unique transaction id
       associated with the specified transaction.  Locking  calls
       made  on  behalf  of this transaction should use the value
       returned from DbTxn::id as the  locker  parameter  to  the
       DbLockTab::get or DbLockTab::vec calls.



TRANSACTIONS

       Creating  transaction  protected applications using the Db
       access methods requires little system  customization.   In
       most  cases,  the  default parameters to the locking, log-
       ging, memory pool, and transaction  subsystems  will  suf-
       fice.   Applications can use DbEnv::appinit (see DbEnv(3))
       to perform this initialization, or they may do it  explic-
       itly.

       Each database operation (i.e., any call to a method under-
       lying the handles  returned  by  Db::open  and  Db::cursor
       described  in  Db(3)) is normally performed on behalf of a
       unique locker.  If multiple calls on behalf  of  the  same
       locker are desired, then transactions must be used.

       Once  the  application  has  initialized the Db subsystems
       that it is  using,  it  may  open  the  Db  access  method
       databases.   For applications performing transactions, the
       databases must be opened after  subsystem  initialization,
       and  cannot  be opened as part of a transaction.  Once the
       open Db files should be  closed.   Once  the  Db  database
       files  are  closed,  the  Db  subsystems should be closed,
       either explicitly or by destroying the DbEnv(3) object.

       It is also possible to use the locking, logging and trans-
       action  subsystems  of Db to provide transaction semantics
       to objects other than those described  by  the  Db  access
       methods.   In  these cases, the application will need more
       explicit customization of the subsystems as  well  as  the
       development  of appropriate data-structure-specific recov-
       ery functions.

       For example, consider an application that provides  trans-
       action  semantics  to  data  stored  in  plain  UNIX files
       accessed using the read(2) and write(2) system calls.  The
       operations for which transaction protection is desired are
       bracketed by calls to DbTxnMgr::begin and DbTxn::commit.

       Before data are referenced, the application  must  make  a
       call  to  the  lock  manager, DbLock(3), for a lock of the
       appropriate type (e.g., read) on the object being  locked.
       The object might be a page in the file, a byte, a range of
       bytes, or some key.  It is up to the application to ensure
       that  appropriate  locks  are acquired.  Before a write is
       performed, the application should acquire a write lock  on
       the object, by making an appropriate call to the lock man-
       ager, DbLock(3).  Then, the application should make a call
       to the log manager, DbLog, to record enough information to
       redo the operation in case of failure after commit and  to
       undo  the operation in case of abort.  As discussed in the
       DbLog(3) manual page, the application is  responsible  for
       providing  any necessary structure to the log record.  For
       example, the application must understand what part of  the
       log  record is an operation code, what part identifies the
       file being modified, what part is  redo  information,  and
       what part is undo information.

       After  the  log  message  is  written, the application may
       issue the write  system  call.   After  all  requests  are
       issued,  the  application  may  call  DbTxn::commit.  When
       DbTxn::commit returns, the caller is guaranteed  that  all
       necessary log writes have been written to disk.

       At  any time, the application may call DbTxn::abort, which
       will result in the appropriate calls to the recover method
       to  restore  the ``database'' to a consistent pre-transac-
       tion state.  (The recover method must be  able  to  either
       re-apply  or undo the update depending on the context, for
       each different type of log record.)

       If the application should crash, the recovery process uses
       the  DbLog  interface to read the log and call the recover
       method to restore the database to a consistent state.

       Methods  marked as returning errno will, by default, throw
       an exception that encapsulates the error information.  The
       default error behavior can be changed, see DbException(3).

       The DbTxn::prepare method may fail and  throw  a  DbExcep-
       tion(3)  or  return  errno for any of the errors specified
       for the following DB and library functions:
       DbLog::flush(3), fcntl(2), fflush(3), and strerror(3).

       The  DbTxn::commit  method  may  fail and throw a DbExcep-
       tion(3) or return errno for any of  the  errors  specified
       for the following DB and library functions:
       DbLockTab::vec(3), DbLog::put(3), fcntl(2), fflush(3),
       malloc(3), memcpy(3), and strerror(3).

       In addition, the DbTxn::commit method may fail and throw a
       DbException(3) or return errno for  the  following  condi-
       tions:

       [EINVAL]
            The transaction was aborted.

       The  DbTxn::abort  method  may  fail  and throw a DbExcep-
       tion(3) or return errno for any of  the  errors  specified
       for the following DB and library functions:
       DBenv->tx_recover(3), DbLockTab::vec(3), DbLog::get(3),
       fcntl(2), fflush(3), memset(3), and strerror(3).

       [EINVAL]
            The transaction was already aborted.


SEE ALSO

       LIBTP:  Portable,  Modular  Transactions  for  UNIX, Margo
       Seltzer, Michael Olson, USENIX proceedings, Winter 1992.


BUGS

       Nested transactions are not yet implemented.

       db_archive(1), db_checkpoint(1), db_deadlock(1), db_dump(1),
       db_load(1), db_recover(1), db_stat(1), db_intro(3), db_jump(3),
       db_thread(3), Db(3), Dbc(3), DbEnv(3), DbException(3), DbInfo(3),
       DbLock(3), DbLocktab(3), DbLog(3), DbLsn(3), DbMpool(3),
       DbMpoolFile(3), Dbt(3), DbTxn(3), DbTxnMgr(3)