DbTxnMgr
import com.sleepycat.db.*;
public static DbTxnMgr open(String dir, int flags, int mode, DbEnv dbenv)
throws DbException;
public DbTxn begin(DbTxn pid)
throws DbException;
public void checkpoint(int kbyte, int min)
throws DbException;
public void close()
throws DbException;
public static void unlink(String dir, int force, DbEnv dbenv)
throws DbException;
public DbTxnStat stat()
throws DbException;
DESCRIPTION
The DB library is a family of classes that provides a
modular programming interface to transactions and record-
oriented 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
package, see db_intro(3).
This manual page describes the specific details of the Db
transaction support. The DbTxnMgr class is used in
conjunction 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 DbMpool(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
provided 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).
DbTxnMgr.open
The DbTxnMgr.open method returns a transaction region
identified by the directory dir.
If the dbenv argument to DbTxnMgr.open was initialized
using DbEnv.appinit, dir is interpreted as described by
DbEnv(3).
Otherwise, if dir is not null, it is interpreted relative
to the current working directory of the process. If dir
is null, the following environment variables are checked
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
created in this directory. This directory must already
exist when DbTxnMgr.open 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.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.DB_THREAD
Cause the DbTxnMgr handle returned by the
DbTxnMgr.open method to be useable by multiple
threads within a single address space, i.e., to be
``free-threaded''. Threading is assumed in the Java
API, so no special flags are required, and DB
functions will always behave as if the DB_THREAD flag
was specified.
Db.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
object used by DbTxnMgr.open are described below. As
references to the DbEnv object may be maintained by
DbTxnMgr.open, it is necessary that the DbEnv object and
memory it references be valid until the object is
destroyed. Any of the DbEnv fields that are not
explicitly set will default to appropriate values.
The following fields in the DbEnv object may be
initialized, using the appropriate set method, before
calling DbTxnMgr.open:
DbErrcall db_errcall;
String db_errpfx;
int db_verbose;
The error fields of the DbEnv behave as described for
DbEnv(3). void *(*db_errcall)(char *db_errpfx, char
*buffer);
FILE *db_errfile;
const char *db_errpfx;
int db_verbose;
The error fields of the DB_ENV behave as described
for db_appinit(3).
DbLog lg_info;
The logging region that is being used for this
transaction 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
transaction 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
transaction environment.
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.
The DbTxnMgr.open method throws a DbException(3) that
encapsulates an errno on failure.
DbTxnMgr.begin
The DbTxnMgr.begin method creates a new transaction in the
transaction manager, and returns a DbTxn that uniquely
identifies it. 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
transaction may only be used by a single thread.
The DbTxnMgr.begin method throws a DbException(3) that
encapsulates an errno on failure.
DbTxnMgr.close
The DbTxnMgr.close method detaches a process from the
transaction environment specified by the DbTxnMgr object.
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
concurrently, only a single thread may call the
DbTxnMgr.close method.
The DbTxnMgr.close method throws a DbException(3) that
encapsulates an errno on failure.
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 called
DbTxnMgr.open without calling DbTxnMgr.close (i.e., there
are processes currently using the transaction region),
DbTxnMgr.unlink will fail without further action, unless
the force flag is set, in which case DbTxnMgr.unlink will
attempt to remove the transaction region files regardless
of any processes still using the transaction region.
The result of attempting to forcibly destroy the region
when a process has the region open is unspecified.
Processes using a shared memory region maintain an open
file descriptor for it. On UNIX systems, the region
removal 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
transaction 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_recover(1) or the
DB_RECOVER and DB_RECOVER_FATAL 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 directory 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 environment.
The DbTxnMgr.unlink method throws a DbException(3) that
encapsulates an errno on failure.
DbTxnMgr.checkpoint
The DbTxnMgr.checkpoint method syncs the underlying memory
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)
that encapsulates an errno on failure, and DB_INCOMPLETE
if there were pages that needed to be written but that
DbMpool.sync (3) (see DbMpool (3)) was unable to write
immediately. In this case, the DbTxnMgr.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 DbTxnStat object encapsulating a
statistical structure.
The transaction region statistics are stored in a
DbTxnStat object. The following methods are available on
DbTxnStat:
DbLsn get_st_last_ckp();
The LSN of the last checkpoint.
DbLsn get_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.
int get_st_time_ckp();
The time the last completed checkpoint finished (as
returned by time(2)).
int get_st_last_txnid();
The last transaction ID allocated.
int get_st_maxtxns();
The maximum number of active transactions supported
by the region.
int get_st_naborts();
The number of transactions that have aborted.
int get_st_nactive();
The number of transactions that are currently active.
int get_st_nbegins();
The number of transactions that have begun.
int get_st_ncommits();
The number of transactions that have committed.
st_region_wait get_();
The number of times that a thread of control was
forced to wait before obtaining the region lock.
st_region_nowait get_();
The number of times that a thread of control was able
to obtain the region lock without waiting.
ENVIRONMENT VARIABLES
The following environment variables affect the execution
of db_txn:
DB_HOME
If the dbenv argument to DbTxnMgr.open was
initialized 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 DbTxnMgr.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
DbTxnMgr.open section above.
ERRORS
The DbTxnMgr.open method may fail and throw a
DbException(3) for any of the errors specified for the
following DB and library functions: DbTxnMgr.unlink(3),
close(2), db_version(3), fcntl(2), fflush(3), lseek(2),
malloc(3), memcpy(3), memset(3), 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) encapsulating an errno for the following
conditions:
[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
DbException(3) 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) encapsulating an errno for the following
conditions:
[ENOSPC]
The maximum number of concurrent transactions has
been reached.
The DbTxnMgr.checkpoint method may fail and throw a
DbException(3) 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
DbException(3) 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
DbException(3) 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), mmap(2),
munmap(2), open(2), sigfillset(3), sigprocmask(2),
stat(2), strcpy(3), strdup(3), strerror(3), strlen(3), and
unlink(2).
In addition, the DbTxnMgr.unlink method may fail and throw
a DbException(3) encapsulating an errno for the following
conditions:
[EBUSY]
The shared memory region was in use and the force
flag was not set.
The DbTxnMgr.stat method may fail and throw a
DbException(3) 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_internal(3), db_thread(3), Db(3), Dbc(3), DbEnv(3),
DbException(3), DbInfo(3), DbLock(3), DbLockTab(3), DbLog(3),
DbLsn(3), DbMpool(3), Dbt(3), DbTxn(3), DbTxnMgr(3)
Man(1) output converted with
man2html