DbTxnMgr
NAME
DbTxnMgr - Db transaction management
SYNOPSIS
#include <db_cxx.h>
static int
DbTxnMgr::open(const char *dir,
int flags, int mode, DbEnv *dbenv, DbTxnMgr **regionp);
int
DbTxnMgr::begin(DbTxn *pid, DbTxn **tid);
int
DbTxnMgr::checkpoint(int kbyte, int min) const;
int
DbTxnMgr::close();
static int
DbTxnMgr::unlink(const char *dir, int force, DbEnv *dbenv);
int
DbTxnMgr::stat(DB_TXN_STAT **statp, void *(*db_malloc)(size_t));
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 DbTxnMgr class is used in con-
junction with DbTxn(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).
in order: ``TMPDIR'', ``TEMP'', and ``TMP''. If one of
them is set, transaction region files are created relative
to the directory it specifies. If none of them are set,
the first possible one of the following directories is
used: /var/tmp, /usr/tmp, /temp, /tmp, C:/temp and C:/tmp.
All files associated with the transaction region are cre-
ated in this directory. This directory must already exist
when is called. If the transaction region already exists,
the process must have permission to read and write the
existing files. If the transaction region does not
already exist, it is optionally created and initialized.
The flags and mode arguments specify how files will be
opened and/or created when they don't already exist. The
flags value is specified by or'ing together one or more of
the following values:
DB_CREATE
Create any underlying files, as necessary. If the
files do not already exist and the DB_CREATE flag is
not specified, the call will fail.
DB_THREAD
Cause the DbTxnMgr handle returned by the DbTxn-
Mgr::open method to be useable by multiple threads
within a single address space, i.e., to be ``free-
threaded''.
DB_TXN_NOSYNC
On transaction commit, do not synchronously flush the
log. This means that transactions exhibit the ACI
(atomicity, consistency and isolation) properties,
but not D (durability), i.e., database integrity will
be maintained but it is possible that some number of
the most recently committed transactions may be
undone during recovery instead of being redone.
The number of transactions that are potentially at
risk is governed by how often the log is checkpointed
(see db_checkpoint(1)) and how many log updates can
fit on a single log page.
All files created by the transaction subsystem are created
with mode mode (as described in chmod(2)) and modified by
the process' umask value at the time of creation (see
umask(2)). The group ownership of created files is based
on the system and directory defaults, and is not further
specified by DB.
The transaction subsystem is configured based on which set
methods have been used. It is expected that applications
will use a single DbEnv object as the argument to all of
the subsystems in the DB package. The fields of the DbEnv
void *(*db_errcall)(char *db_errpfx, char *buffer);
FILE *db_errfile;
const char *db_errpfx;
class ostream *db_error_stream;
int db_verbose;
The error fields of the DbEnv behave as described for
DbEnv(3).
DbLog *lg_info;
The logging region that is being used for this trans-
action environment. The lg_info field contains a
return value from the method DbLog::open. Logging is
required for transaction environments, and it is an
error to not specify a logging region.
DbLockTab *lk_info;
The locking region that is being used for this trans-
action environment. The lk_info field contains a
return value from the method DbLockTab::open. If
lk_info is NULL, no locking is done in this transac-
tion environment.
unsigned int tx_max;
The maximum number of simultaneous transactions that
are supported. This bounds the size of backing files
and is used to derive limits for the size of the lock
region and logfiles. When there are more than tx_max
concurrent transactions, calls to DbTxnMgr::begin may
cause backing files to grow. If tx_max is 0, a
default value is used.
int DbTxnMgr::recover(DbLog *logp, Dbt *DbLog::rec,
DbLsn *lsnp, int redo, void *info);
A method that is called by DbTxn::abort during trans-
action abort. This method takes five arguments:
logp A pointer to the transaction log (DbLog *).
DbLog::rec
A log record.
lsnp A pointer to a log sequence number (DbLsn *).
redo An integer value that is set to one of the fol-
lowing values:
DB_TXN_BACKWARD_ROLL
The log is being read backward to determine
which transactions have been committed and
which transactions were not (and should
therefore be aborted during recovery).
DB_TXN_FORWARD_ROLL
The log is being played forward, any trans-
DB_TXN_UNDO
Undo the operation described by the log
record.
info An opaque pointer used to reference the list of
transaction IDs encountered during recovery.
If recover is NULL, the default is that only Db
access method operations are transaction protected,
and the default recover method will be used.
The DbTxnMgr::open method throws a DbException(3) or
returns the value of errno on failure and 0 on success.
DbTxnMgr::begin
The DbTxnMgr::begin method creates a new transaction in
the transaction manager, copying a pointer to a DbTxn that
uniquely identifies it into the memory referenced by tid.
If the pid argument is non-NULL, the new transaction is a
nested transaction with the transaction indicated by pid
as its parent.
Transactions may not span threads, i.e., each transaction
must begin and end in the same thread, and each transac-
tion may only be used by a single thread.
The DbTxnMgr::begin method throws a DbException(3) or
returns the value of errno on failure and 0 on success.
DbTxnMgr::close
The DbTxnMgr::close method detaches a process from the
transaction environment specified by the DbTxnMgr pointer.
All mapped regions are unmapped and any allocated
resources are freed. Any uncommitted transactions are
aborted.
In addition, if the dir argument to DbTxnMgr::open was
NULL and dbenv was not initialized using DbEnv::appinit,
all files created for this shared region will be removed,
as if DbTxnMgr::unlink were called.
When multiple threads are using the DbTxnMgr handle con-
currently, only a single thread may call the DbTxn-
Mgr::close method.
The DbTxnMgr::close method throws a DbException(3) or
returns the value of errno on failure and 0 on success.
DbTxnMgr::unlink
The DbTxnMgr::unlink method destroys the transaction
region identified by the directory dir, removing all files
used to implement the transaction region. (The directory
dir is not removed.) If there are processes that have
should succeed and processes that have already joined the
region should continue to run in the region without
change, however processes attempting to join the transac-
tion region will either fail or attempt to create a new
region. On other systems, e.g., WNT, where the unlink(2)
system call will fail if any process has an open file
descriptor for the file, the region removal will fail.
In the case of catastrophic or system failure, database
recovery must be performed (see db_recovery(1) or the
DB_RECOVER flags to DbEnv::appinit(3)). Alternatively, if
recovery is not required because no database state is
maintained across failures, it is possible to clean up a
transaction region by removing all of the files in the
directory specified to the DbTxnMgr::open method, as
transaction region files are never created in any direc-
tory other than the one specified to DbTxnMgr::open.
Note, however, that this has the potential to remove files
created by the other DB subsystems in this database envi-
ronment.
The DbTxnMgr::unlink method throws a DbException(3) or
returns the value of errno on failure and 0 on success.
DbTxnMgr::checkpoint
The DbTxnMgr::checkpoint method syncs the underlying mem-
ory pool, writes a checkpoint record to the log and then
flushes the log.
If either kbyte or min is non-zero, the checkpoint is only
done if more than min minutes have passed since the last
checkpoint, or if more than kbyte kilobytes of log data
have been written since the last checkpoint.
The DbTxnMgr::checkpoint method throws a DbException(3) or
returns the value of errno on failure, 0 on success, and
DB_INCOMPLETE if there were pages that needed to be writ-
ten but that DbMpool::sync (3) (see DbMpool (3)) was
unable to write immediately. In this case, the DbTxn-
Mgr::checkpoint call should be retried.
The DbTxnMgr::checkpoint method is based on the C
txn_checkpoint function, which is the underlying function
used by the db_checkpoint(1) utility. See the source code
for the db_checkpoint utility for an example of using
txn_checkpoint in a UNIX environment.
DbTxnMgr::stat
The DbTxnMgr::stat method creates a statistical structure
and copies pointers to it into user-specified memory loca-
tions.
Statistical structures are created in allocated memory.
If db_malloc is non-NULL, it is called to allocate the
DbLsn st_last_ckp;
The LSN of the last checkpoint.
DbLsn st_pending_ckp;
The LSN of any checkpoint that is currently in
progress. If st_pending_ckp is the same as
st_last_ckp there is no checkpoint in progress.
time_t st_time_ckp;
The time the last completed checkpoint finished (as
returned by time(2)).
u_int32_t st_last_txnid;
The last transaction ID allocated.
u_int32_t st_maxtxns;
The maximum number of active transactions supported
by the region.
u_int32_t st_naborts;
The number of transactions that have aborted.
u_int32_t st_nactive;
The number of transactions that are currently active.
u_int32_t st_nbegins;
The number of transactions that have begun.
u_int32_t st_ncommits;
The number of transactions that have committed.
DB_TXN_ACTIVE *st_txnarray;
A pointer to an array of st_nactive DB_TXN_ACTIVE
structures, describing the currently active transac-
tions. The following fields of the DB_TXN_ACTIVE
structure (typedef'd in <db_cxx.h>) will be filled
in:
u_int32_t txnid;
The transaction ID as returned by DbTxn-
Mgr::begin(3).
DbLsn lsn;
The LSN of the transaction-begin record.
ENVIRONMENT VARIABLES
The following environment variables affect the execution
of db_txn:
DB_HOME
If the dbenv argument to DbTxnMgr::open was initial-
ized using db_appinit, the environment variable
DB_HOME may be used as the path of the database home
for the interpretation of the dir argument to DbTxn-
Mgr::open, as described in db_appinit(3).
TMPDIR
If the dbenv argument to DbTxnMgr::open was NULL or
not initialized using db_appinit, the environment
variable TMPDIR may be used as the directory in which
to create the transaction region, as described in the
mmap(2), munmap(2), open(2), sigfillset(3),
sigprocmask(2), stat(2), strcpy(3), strdup(3),
strerror(3), strlen(3), time(3), unlink(2), and write(2).
In addition, the DbTxnMgr::open method may fail and throw
a DbException(3) or return errno for the following condi-
tions:
[EINVAL]
An invalid flag value or parameter was specified.
The DB_THREAD flag was specified and spinlocks are
not implemented for this architecture.
The dbenv parameter was NULL.
[EAGAIN]
The shared memory region was locked and (repeatedly)
unavailable.
The DbTxnMgr::begin 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::put(3),
fcntl(2), fflush(3), lseek(2), malloc(3), memcpy(3),
memset(3), mmap(2), munmap(2), strerror(3), and write(2).
In addition, the DbTxnMgr::begin method may fail and throw
a DbException(3) or return errno for the following condi-
tions:
[ENOSPC]
The maximum number of concurrent transactions has
been reached.
The DbTxnMgr::checkpoint method may fail and throw a DbEx-
ception(3) or return errno for any of the errors specified
for the following DB and library functions:
DbLog::compare(3), DbLog::put(3), DbMpool::sync(3),
fcntl(2), fflush(3), malloc(3), memcpy(3), memset(3),
strerror(3), and time(3).
[EINVAL]
An invalid flag value or parameter was specified.
The DbTxnMgr::close 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), DbTxn::abort(3), close(2), fcntl(2),
fflush(3), munmap(2), and strerror(3).
The DbTxnMgr::unlink 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: close(2),
fcntl(2), fflush(3), malloc(3), memcpy(3), memset(3),
The DbTxnMgr::stat 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: fcntl(2), and
malloc(3).
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)