зеркало из https://github.com/mozilla/gecko-dev.git
441 строка
22 KiB
HTML
441 строка
22 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>DbTxnMgr</TITLE>
|
|
</HEAD>
|
|
<BODY BGCOLOR=white>
|
|
<H1>DbTxnMgr</H1>
|
|
<HR SIZE=1 NOSHADE>
|
|
<PRE>
|
|
<!-- Manpage converted by man2html 3.0.1 -->
|
|
<B>import</B> <B>com.sleepycat.db.*;</B>
|
|
|
|
<B>public</B> <B>static</B> <B>DbTxnMgr</B> <B>open(String</B> <B>dir,</B> <B>int</B> <B>flags,</B> <B>int</B> <B>mode,</B> <B>DbEnv</B> <B>dbenv)</B>
|
|
<B>throws</B> <B>DbException;</B>
|
|
|
|
<B>public</B> <B>DbTxn</B> <B>begin(DbTxn</B> <B>pid)</B>
|
|
<B>throws</B> <B>DbException;</B>
|
|
|
|
<B>public</B> <B>void</B> <B>checkpoint(int</B> <B>kbyte,</B> <B>int</B> <B>min)</B>
|
|
<B>throws</B> <B>DbException;</B>
|
|
|
|
<B>public</B> <B>void</B> <B>close()</B>
|
|
<B>throws</B> <B>DbException;</B>
|
|
|
|
<B>public</B> <B>static</B> <B>void</B> <B>unlink(String</B> <B>dir,</B> <B>int</B> <B>force,</B> <B>DbEnv</B> <B>dbenv)</B>
|
|
<B>throws</B> <B>DbException;</B>
|
|
|
|
<B>public</B> <B>DbTxnStat</B> <B>stat()</B>
|
|
<B>throws</B> <B>DbException;</B>
|
|
|
|
|
|
</PRE>
|
|
<H2>DESCRIPTION</H2><PRE>
|
|
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 <B><A HREF="db_intro.html">db_intro(3)</A></B>.
|
|
|
|
This manual page describes the specific details of the Db
|
|
transaction support. The DbTxnMgr class is used in
|
|
conjunction with <B><A HREF="DbTxn.j.html">DbTxn(3)</A></B> 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 <B><A HREF="DbLog.j.html">DbLog(3)</A></B>), concurrency control
|
|
(see <B><A HREF="DbLock.j.html">DbLock(3)</A></B> and <B><A HREF="DbLockTab.j.html">DbLockTab(3)</A></B>), and the management of
|
|
shared data (see <B><A HREF="DbMpool.j.html">DbMpool(3)</A></B> and <B><A HREF="DbMpoolFile.html">DbMpoolFile(3)</A></B>).
|
|
Transaction semantics can be applied to the access methods
|
|
described in <B><A HREF="Db.j.html">Db(3)</A></B> 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 <B><A HREF="DbLog.j.html">DbLog(3)</A></B> 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 <B>directory</B> dir.
|
|
|
|
If the dbenv argument to DbTxnMgr.open was initialized
|
|
using DbEnv.appinit, dir is interpreted as described by
|
|
<B><A HREF="DbEnv.j.html">DbEnv(3)</A></B>.
|
|
|
|
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 <B>or</B>'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 <B><A HREF="db_checkpoint.html">db_checkpoint(1)</A></B>) 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 <B>chmod(2)</B>) and modified by
|
|
the process' umask value at the time of creation (see
|
|
<B>umask(2)</B>). 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
|
|
<B><A HREF="DbEnv.j.html">DbEnv(3)</A></B>. 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 <B><A HREF="db_appinit.html">db_appinit(3)</A></B>.
|
|
|
|
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. <B>Logging</B>
|
|
<B>is</B> <B>required</B> <B>for</B> <B>transaction</B> <B>environments,</B> <B>and</B> <B>it</B> <B>is</B>
|
|
<B>an</B> <B>error</B> <B>to</B> <B>not</B> <B>specify</B> <B>a</B> <B>logging</B> <B>region.</B>
|
|
|
|
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 <B><A HREF="DbException.j.html">DbException(3)</A></B> 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 <B><A HREF="DbException.j.html">DbException(3)</A></B> 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 <B><A HREF="DbException.j.html">DbException(3)</A></B> 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
|
|
<B>unlink(2)</B> 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 <B><A HREF="db_recover.html">db_recover(1)</A></B> or the
|
|
DB_RECOVER and DB_RECOVER_FATAL flags to
|
|
<B><A HREF="DbEnv.j.html">DbEnv.appinit(3)</A></B>). 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 <B><A HREF="DbException.j.html">DbException(3)</A></B> 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 <B><A HREF="DbException.j.html">DbException(3)</A></B>
|
|
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 <B><A HREF="db_checkpoint.html">db_checkpoint(1)</A></B> 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 <B>time(2)</B>).
|
|
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.
|
|
|
|
|
|
</PRE>
|
|
<H2>ENVIRONMENT VARIABLES</H2><PRE>
|
|
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
|
|
<B><A HREF="db_appinit.html">db_appinit(3)</A></B>.
|
|
|
|
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.
|
|
|
|
|
|
</PRE>
|
|
<H2>ERRORS</H2><PRE>
|
|
The DbTxnMgr.open method may fail and throw a
|
|
<B><A HREF="DbException.j.html">DbException(3)</A></B> for any of the errors specified for the
|
|
following DB and library functions: <B><A HREF="DbTxnMgr.j.html">DbTxnMgr.unlink(3)</A></B>,
|
|
<B>close(2)</B>, <B><A HREF="db_appinit.html">db_version(3)</A></B>, <B>fcntl(2)</B>, <B>fflush(3)</B>, <B>lseek(2)</B>,
|
|
<B>malloc(3)</B>, <B>memcpy(3)</B>, <B>memset(3)</B>, <B>mmap(2)</B>, <B>munmap(2)</B>,
|
|
<B>open(2)</B>, <B>sigfillset(3)</B>, <B>sigprocmask(2)</B>, <B>stat(2)</B>,
|
|
<B>strcpy(3)</B>, <B>strdup(3)</B>, <B>strerror(3)</B>, <B>strlen(3)</B>, <B>time(3)</B>,
|
|
<B>unlink(2)</B>, and <B>write(2)</B>.
|
|
|
|
In addition, the DbTxnMgr.open method may fail and throw a
|
|
<B><A HREF="DbException.j.html">DbException(3)</A></B> 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
|
|
<B><A HREF="DbException.j.html">DbException(3)</A></B> for any of the errors specified for the
|
|
following DB and library functions: <B><A HREF="DbLog.j.html">DbLog.put(3)</A></B>,
|
|
<B>fcntl(2)</B>, <B>fflush(3)</B>, <B>lseek(2)</B>, <B>malloc(3)</B>, <B>memcpy(3)</B>,
|
|
<B>memset(3)</B>, <B>mmap(2)</B>, <B>munmap(2)</B>, <B>strerror(3)</B>, and <B>write(2)</B>.
|
|
|
|
In addition, the DbTxnMgr.begin method may fail and throw
|
|
a <B><A HREF="DbException.j.html">DbException(3)</A></B> 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
|
|
<B><A HREF="DbException.j.html">DbException(3)</A></B> for any of the errors specified for the
|
|
following DB and library functions: <B><A HREF="DbLog.j.html">DbLog.compare(3)</A></B>,
|
|
<B><A HREF="DbLog.j.html">DbLog.put(3)</A></B>, <B><A HREF="DbMpool.j.html">DbMpool.sync(3)</A></B>, <B>fcntl(2)</B>, <B>fflush(3)</B>,
|
|
<B>malloc(3)</B>, <B>memcpy(3)</B>, <B>memset(3)</B>, <B>strerror(3)</B>, and <B>time(3)</B>.
|
|
|
|
[EINVAL]
|
|
An invalid flag value or parameter was specified.
|
|
|
|
The DbTxnMgr.close method may fail and throw a
|
|
<B><A HREF="DbException.j.html">DbException(3)</A></B> for any of the errors specified for the
|
|
following DB and library functions: <B><A HREF="DbLog.j.html">DbLog.flush(3)</A></B>,
|
|
<B><A HREF="DbTxn.j.html">DbTxn.abort(3)</A></B>, <B>close(2)</B>, <B>fcntl(2)</B>, <B>fflush(3)</B>, <B>munmap(2)</B>,
|
|
and <B>strerror(3)</B>.
|
|
|
|
The DbTxnMgr.unlink method may fail and throw a
|
|
<B><A HREF="DbException.j.html">DbException(3)</A></B> for any of the errors specified for the
|
|
following DB and library functions: <B>close(2)</B>, <B>fcntl(2)</B>,
|
|
<B>fflush(3)</B>, <B>malloc(3)</B>, <B>memcpy(3)</B>, <B>memset(3)</B>, <B>mmap(2)</B>,
|
|
<B>munmap(2)</B>, <B>open(2)</B>, <B>sigfillset(3)</B>, <B>sigprocmask(2)</B>,
|
|
<B>stat(2)</B>, <B>strcpy(3)</B>, <B>strdup(3)</B>, <B>strerror(3)</B>, <B>strlen(3)</B>, and
|
|
<B>unlink(2)</B>.
|
|
|
|
In addition, the DbTxnMgr.unlink method may fail and throw
|
|
a <B><A HREF="DbException.j.html">DbException(3)</A></B> 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
|
|
<B><A HREF="DbException.j.html">DbException(3)</A></B> for any of the errors specified for the
|
|
following DB and library functions: <B>fcntl(2)</B>, and
|
|
<B>malloc(3)</B>.
|
|
|
|
|
|
</PRE>
|
|
<H2>SEE ALSO</H2><PRE>
|
|
LIBTP: Portable, Modular Transactions for UNIX, Margo
|
|
Seltzer, Michael Olson, USENIX proceedings, Winter 1992.
|
|
|
|
|
|
</PRE>
|
|
<H2>BUGS</H2><PRE>
|
|
Nested transactions are not yet implemented.
|
|
|
|
<B><A HREF="db_archive.html">db_archive(1)</A></B>, <B><A HREF="db_checkpoint.html">db_checkpoint(1)</A></B>, <B><A HREF="db_deadlock.html">db_deadlock(1)</A></B>, <B><A HREF="db_dump.html">db_dump(1)</A></B>,
|
|
<B><A HREF="db_load.html">db_load(1)</A></B>, <B><A HREF="db_recover.html">db_recover(1)</A></B>, <B><A HREF="db_stat.html">db_stat(1)</A></B>, <B><A HREF="db_intro.html">db_intro(3)</A></B>,
|
|
<B><A HREF="db_internal.html">db_internal(3)</A></B>, <B><A HREF="db_thread.html">db_thread(3)</A></B>, <B><A HREF="Db.j.html">Db(3)</A></B>, <B><A HREF="Dbc.j.html">Dbc(3)</A></B>, <B><A HREF="DbEnv.j.html">DbEnv(3)</A></B>,
|
|
<B><A HREF="DbException.j.html">DbException(3)</A></B>, <B><A HREF="DbInfo.j.html">DbInfo(3)</A></B>, <B><A HREF="DbLock.j.html">DbLock(3)</A></B>, <B><A HREF="DbLockTab.j.html">DbLockTab(3)</A></B>, <B><A HREF="DbLog.j.html">DbLog(3)</A></B>,
|
|
<B><A HREF="DbLsn.j.html">DbLsn(3)</A></B>, <B><A HREF="DbMpool.j.html">DbMpool(3)</A></B>, <B><A HREF="Dbt.j.html">Dbt(3)</A></B>, <B><A HREF="DbTxn.j.html">DbTxn(3)</A></B>, <B><A HREF="DbTxnMgr.j.html">DbTxnMgr(3)</A></B>
|
|
|
|
</PRE>
|
|
<HR SIZE=1 NOSHADE>
|
|
<ADDRESS>
|
|
Man(1) output converted with
|
|
<a href="http://www.oac.uci.edu/indiv/ehood/man2html.html">man2html</a>
|
|
</ADDRESS>
|
|
</BODY>
|
|
</HTML>
|