зеркало из https://github.com/mozilla/gecko-dev.git
721 строка
34 KiB
HTML
721 строка
34 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>db_txn</TITLE>
|
|
</HEAD>
|
|
<BODY BGCOLOR=white>
|
|
<H1>db_txn</H1>
|
|
<HR SIZE=1 NOSHADE>
|
|
<PRE>
|
|
<!-- Manpage converted by man2html 3.0.1 -->
|
|
<B>#include</B> <B><db.h></B>
|
|
|
|
<B>int</B>
|
|
<B>txn</B>_<B>open(const</B> <B>char</B> <B>*dir,</B>
|
|
<B>u</B>_<B>int32</B>_<B>t</B> <B>flags,</B> <B>int</B> <B>mode,</B> <B>DB</B>_<B>ENV</B> <B>*dbenv,</B> <B>DB</B>_<B>TXNMGR</B> <B>**regionp);</B>
|
|
|
|
<B>int</B>
|
|
<B>txn</B>_<B>begin(DB</B>_<B>TXNMGR</B> <B>*txnp,</B> <B>DB</B>_<B>TXN</B> <B>*pid,</B> <B>DB</B>_<B>TXN</B> <B>**tid);</B>
|
|
|
|
<B>int</B>
|
|
<B>txn</B>_<B>prepare(DB</B>_<B>TXN</B> <B>*tid);</B>
|
|
|
|
<B>int</B>
|
|
<B>txn</B>_<B>commit(DB</B>_<B>TXN</B> <B>*tid);</B>
|
|
|
|
<B>int</B>
|
|
<B>txn</B>_<B>abort(DB</B>_<B>TXN</B> <B>*tid);</B>
|
|
|
|
<B>u</B>_<B>int32</B>_<B>t</B>
|
|
<B>txn</B>_<B>id(DB</B>_<B>TXN</B> <B>*tid);</B>
|
|
|
|
<B>int</B>
|
|
<B>txn</B>_<B>checkpoint(const</B> <B>DB</B>_<B>TXNMGR</B> <B>*txnp,</B> <B>u</B>_<B>int32</B>_<B>t</B> <B>kbyte,</B> <B>u</B>_<B>int32</B>_<B>t</B> <B>min);</B>
|
|
|
|
<B>int</B>
|
|
<B>txn</B>_<B>close(DB</B>_<B>TXNMGR</B> <B>*txnp);</B>
|
|
|
|
<B>int</B>
|
|
<B>txn</B>_<B>unlink(const</B> <B>char</B> <B>*dir,</B> <B>int</B> <B>force,</B> <B>DB</B>_<B>ENV</B> <B>*dbenv);</B>
|
|
|
|
<B>int</B>
|
|
<B>txn</B>_<B>stat(DB</B>_<B>TXNMGR</B> <B>*txnp,</B>
|
|
<B>DB</B>_<B>TXN</B>_<B>STAT</B> <B>**statp,</B> <B>void</B> <B>*(*db</B>_<B>malloc)(size</B>_<B>t));</B>
|
|
|
|
|
|
</PRE>
|
|
<H2>DESCRIPTION</H2><PRE>
|
|
The DB library is a family of groups of functions 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 functional groups (e.g., the file page caching
|
|
functions) are useful independent of the other DB
|
|
functions, although some functional groups are explicitly
|
|
based on other functional groups (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 db_txn functions are the library interface that
|
|
provides 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="db_log.html">db_log(3)</A></B>),
|
|
concurrency control (see <B><A HREF="db_lock.html">db_lock(3)</A></B>), and the management
|
|
of shared data (see <B><A HREF="db_mpool.html">db_mpool(3)</A></B>). Transaction semantics
|
|
can be applied to the access methods described in
|
|
<B><A HREF="db_open.html">db_open(3)</A></B> through function call parameters.
|
|
|
|
The model intended for transactional use (and the one that
|
|
is used by the access methods) is write-ahead logging
|
|
provided by <B><A HREF="db_log.html">db_log(3)</A></B> to record both before- and after-
|
|
images. Locking follows a two-phase protocol, with all
|
|
locks being released at transaction commit.
|
|
|
|
txn_open
|
|
The txn_open function copies a pointer, to the transaction
|
|
region identified by the <B>directory</B> dir, into the memory
|
|
location referenced by regionp.
|
|
|
|
If the dbenv argument to txn_open was initialized using
|
|
db_appinit, dir is interpreted as described by
|
|
<B><A HREF="db_appinit.html">db_appinit(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
|
|
|
|
transaction region_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_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 DB_TXNMGR handle returned by the txn_open
|
|
function 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 <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 the dbenv
|
|
argument to txn_open, which is a pointer to a structure of
|
|
type DB_ENV (typedef'd in <db.h>). Applications will
|
|
normally use the same DB_ENV structure (initialized by
|
|
<B><A HREF="db_appinit.html">db_appinit(3)</A></B>), as an argument to all of the subsystems in
|
|
the DB package.
|
|
|
|
References to the DB_ENV structure are maintained by DB,
|
|
so it may not be discarded until the last close function,
|
|
corresponding to an open function for which it was an
|
|
argument, has returned. In order to ensure compatibility
|
|
with future releases of DB, all fields of the DB_ENV
|
|
structure that are not explicitly set should be
|
|
initialized to 0 before the first time the structure is
|
|
used. Do this by declaring the structure external or
|
|
static, or by calling the C library routine <B>bzero(3)</B> or
|
|
<B>memset(3)</B>.
|
|
|
|
The fields of the DB_ENV structure used by txn_open are
|
|
described below. If dbenv is NULL or any of its fields
|
|
are set to 0, defaults appropriate for the system are used
|
|
where possible.
|
|
|
|
The following fields in the DB_ENV structure may be
|
|
initialized before calling txn_open:
|
|
|
|
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>.
|
|
|
|
DB_LOG *lg_info;
|
|
The logging region that is being used for this
|
|
transaction environment. The lg_info field contains
|
|
a return value from the function log_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>
|
|
|
|
DB_LOCKTAB *lk_info;
|
|
The locking region that is being used for this
|
|
transaction environment. The lk_info field contains
|
|
a return value from the function lock_open. If
|
|
lk_info is NULL, no locking is done in this
|
|
transaction environment.
|
|
|
|
u_int32_t 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 txn_begin may cause
|
|
backing files to grow. If tx_max is 0, a default
|
|
value is used.
|
|
|
|
int (*tx_recover)(DB_LOG *logp, DBT *log_rec,
|
|
DB_LSN *lsnp, int redo, void *info);
|
|
A function that is called by txn_abort during
|
|
transaction abort. This function takes five
|
|
arguments:
|
|
|
|
logp A pointer to the transaction log (DB_LOG *).
|
|
|
|
log_rec
|
|
A log record.
|
|
|
|
lsnp A pointer to a log sequence number (DB_LSN *).
|
|
|
|
redo An integer value that is set to one of the
|
|
following 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
|
|
transaction ids encountered that have not
|
|
been entered into the list referenced by
|
|
info should be ignored.
|
|
|
|
DB_TXN_OPENFILES
|
|
The log is being read to open all the files
|
|
required to perform recovery.
|
|
|
|
DB_TXN_REDO
|
|
Redo the operation described by the log
|
|
record.
|
|
|
|
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 function will be used.
|
|
|
|
The txn_open function returns the value of errno on
|
|
failure and 0 on success.
|
|
|
|
txn_begin
|
|
The txn_begin function creates a new transaction in the
|
|
designated transaction manager, copying a pointer to a
|
|
DB_TXN 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
|
|
transaction may only be used by a single thread.
|
|
|
|
The txn_begin function returns the value of errno on
|
|
failure and 0 on success.
|
|
|
|
txn_prepare
|
|
The txn_prepare function 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
|
|
prepare messages to each local manager. The local manager
|
|
must then issue a txn_prepare and await its successful
|
|
return before responding to the distributed transaction
|
|
manager. Only after the distributed transaction manager
|
|
receives successful responses from all of its prepare
|
|
messages should it issue any commit messages.
|
|
|
|
The txn_prepare function returns the value of errno on
|
|
failure and 0 on success.
|
|
|
|
txn_commit
|
|
The txn_commit function ends the transaction specified by
|
|
the tid argument. If DB_TXN_NOSYNC was not specified, a
|
|
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
|
|
txn_commit.
|
|
|
|
The txn_commit function returns the value of errno on
|
|
failure and 0 on success.
|
|
|
|
txn_abort
|
|
The txn_abort function causes an abnormal termination of
|
|
the transaction. The log is played backwards and any
|
|
necessary recovery operations are initiated through the
|
|
recover function specified to txn_open. After recovery 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
|
|
transaction. As is the case for txn_commit, applications
|
|
that require strict two phase locking should not
|
|
explicitly release any locks.
|
|
|
|
The txn_abort function returns the value of errno on
|
|
failure and 0 on success.
|
|
|
|
txn_id
|
|
The txn_id function returns the unique transaction id
|
|
associated with the specified transaction. Locking calls
|
|
made on behalf of this transaction should use the value
|
|
returned from txn_id as the locker parameter to the
|
|
lock_get or lock_vec calls.
|
|
|
|
txn_close
|
|
The txn_close function detaches a process from the
|
|
transaction environment specified by the DB_TXNMGR
|
|
pointer. All mapped regions are unmapped and any
|
|
allocated resources are freed. Any uncommitted
|
|
transactions are aborted.
|
|
|
|
In addition, if the dir argument to txn_open was NULL and
|
|
dbenv was not initialized using db_appinit, all files
|
|
created for this shared region will be removed, as if
|
|
txn_unlink were called.
|
|
|
|
When multiple threads are using the DB_TXNMGR handle
|
|
concurrently, only a single thread may call the txn_close
|
|
function.
|
|
|
|
The txn_close function returns the value of errno on
|
|
failure and 0 on success.
|
|
|
|
txn_unlink
|
|
The txn_unlink function 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
|
|
txn_open without calling txn_close (i.e., there are
|
|
processes currently using the transaction region),
|
|
txn_unlink will fail without further action, unless the
|
|
force flag is set, in which case txn_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="db_appinit.html">db_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 txn_open
|
|
function, as transaction region files are never created in
|
|
any directory other than the one specified to txn_open.
|
|
Note, however, that this has the potential to remove files
|
|
created by the other DB subsystems in this database
|
|
environment.
|
|
|
|
The txn_unlink function returns the value of errno on
|
|
failure and 0 on success.
|
|
|
|
txn_checkpoint
|
|
The txn_checkpoint function 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 txn_checkpoint function returns the value of errno on
|
|
failure, 0 on success, and DB_INCOMPLETE if there were
|
|
pages that needed to be written but that <B><A HREF="db_mpool.html">memp_sync(3)</A></B> was
|
|
unable to write immediately. In this case, the
|
|
txn_checkpoint call should be retried.
|
|
|
|
The txn_checkpoint function 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.
|
|
|
|
txn_stat
|
|
The txn_stat function creates a statistical structure and
|
|
copies a pointer to it into the user-specified memory
|
|
location.
|
|
|
|
Statistical structure are created in allocated memory. If
|
|
db_malloc is non-NULL, it is called to allocate the
|
|
memory, otherwise, the library function <B>malloc(3)</B> is used.
|
|
The function db_malloc must match the calling conventions
|
|
of the <B>malloc(3)</B> library routine. Regardless, the caller
|
|
is responsible for deallocating the returned memory. To
|
|
deallocate the returned memory, free each returned memory
|
|
pointer; pointers inside the memory do not need to be
|
|
individually freed.
|
|
|
|
The transaction region statistics are stored in a
|
|
structure of type DB_TXN_STAT (typedef'd in <db.h>). The
|
|
following DB_TXN_STAT fields will be filled in:
|
|
|
|
u_int32_t st_refcnt;
|
|
The number of references to the region.
|
|
u_int32_t st_regsize;
|
|
The size of the region.
|
|
DB_LSN st_last_ckp;
|
|
The LSN of the last checkpoint.
|
|
DB_LSN 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 <B>time(2)</B>).
|
|
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.
|
|
|
|
u_int32_t st_region_wait;
|
|
The number of times that a thread of control was
|
|
forced to wait before obtaining the region lock.
|
|
u_int32_t st_region_nowait;
|
|
The number of times that a thread of control was able
|
|
to obtain the region lock without waiting.
|
|
DB_TXN_ACTIVE *st_txnarray;
|
|
A pointer to an array of st_nactive DB_TXN_ACTIVE
|
|
structures, describing the currently active
|
|
transactions. The following fields of the
|
|
DB_TXN_ACTIVE structure (typedef'd in <db.h>) will be
|
|
filled in:
|
|
|
|
u_int32_t txnid;
|
|
The transaction ID as returned by <B><A HREF="db_txn.html">txn_begin(3)</A></B>.
|
|
DB_LSN lsn;
|
|
The LSN of the transaction-begin record.
|
|
|
|
|
|
</PRE>
|
|
<H2>TRANSACTIONS</H2><PRE>
|
|
Creating transaction protected applications using the DB
|
|
access methods requires little system customization. In
|
|
most cases, the default parameters to the locking,
|
|
logging, memory pool, and transaction subsystems will
|
|
suffice. Applications can use <B><A HREF="db_appinit.html">db_appinit(3)</A></B> to perform
|
|
this initialization, or they may do it explicitly.
|
|
|
|
Each database operation (i.e., any call to a function
|
|
underlying the handles returned by <B><A HREF="db_open.html">db_open(3)</A></B> and
|
|
<B><A HREF="db_cursor.html">db_cursor(3)</A></B>) 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
|
|
databases are opened, the application can group sets of
|
|
operations into transactions, by surrounding the
|
|
operations with the appropriate txn_begin, txn_commit and
|
|
txn_abort calls. Databases accessed by a transaction must
|
|
not be closed during the transaction. Note, it is not
|
|
necessary to transaction protect read-only transactions,
|
|
unless those transactions require repeatable reads.
|
|
|
|
The DB access methods will make the appropriate calls into
|
|
the lock, log and memory pool subsystems in order to
|
|
guarantee that transaction semantics are applied. When
|
|
the application is ready to exit, all outstanding
|
|
transactions should have been committed or aborted. At
|
|
this point, all open DB files should be closed. Once the
|
|
DB database files are closed, the DB subsystems should be
|
|
closed, either explicitly or by calling <B><A HREF="db_appinit.html">db_appexit(3)</A></B>.
|
|
|
|
It is also possible to use the locking, logging and
|
|
transaction 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
|
|
recovery functions.
|
|
|
|
For example, consider an application that provides
|
|
transaction semantics to data stored in plain UNIX files
|
|
accessed using the <B>read(2)</B> and <B>write(2)</B> system calls. The
|
|
operations for which transaction protection is desired are
|
|
bracketed by calls to txn_begin and txn_commit.
|
|
|
|
Before data are referenced, the application must make a
|
|
call to the lock manager, db_lock, 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
|
|
manager, db_lock. Then, the application should make a
|
|
call to the log manager, db_log, 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 <B><A HREF="db_log.html">db_log(3)</A></B> 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 txn_commit. When
|
|
txn_commit returns, the caller is guaranteed that all
|
|
necessary log writes have been written to disk.
|
|
|
|
At any time, the application may call txn_abort, which
|
|
will result in the appropriate calls to the recover
|
|
function to restore the ``database'' to a consistent pre-
|
|
transaction state. (The recover function 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 db_log interface to read the log and call the recover
|
|
function to restore the database to a consistent state.
|
|
|
|
The txn_prepare function provides the core functionality
|
|
to implement distributed transactions, but it does not
|
|
manage the notification of distributed transaction
|
|
managers. The caller is responsible for issuing
|
|
txn_prepare calls to all sites participating in the
|
|
transaction. If all responses are positive, the caller
|
|
can issue a txn_commit. If any of the responses are
|
|
negative, the caller should issue a txn_abort. In
|
|
general, the txn_prepare call requires that the
|
|
transaction log be flushed to disk.
|
|
|
|
|
|
</PRE>
|
|
<H2>TRANSACTION ID LIMITS</H2><PRE>
|
|
The transaction ID space in Berkeley DB is 2^31, or 2
|
|
billion entries. It is possible that some environments
|
|
may need to be aware of this limitation. Consider an
|
|
application performing 600 transactions a second for 15
|
|
hours a day. The transaction ID space will run out in
|
|
roughly 66 days:
|
|
|
|
2^31 / (600 * 15 * 60 * 60) = 66
|
|
|
|
Doing only 100 transactions a second exhausts the
|
|
transaction ID space in roughly one year.
|
|
|
|
The transaction ID space is reset each time recovery is
|
|
run. If you reach the end of your transaction ID space,
|
|
shut down your applications and restart them after running
|
|
recovery (see <B><A HREF="db_recover.html">db_recover(1)</A></B> for more information). The
|
|
most recently allocated transaction ID is the
|
|
st_last_txnid value in the transaction statistics
|
|
information, and is displayed by the <B><A HREF="db_stat.html">db_stat(1)</A></B> utility.
|
|
|
|
|
|
</PRE>
|
|
<H2>ENVIRONMENT VARIABLES</H2><PRE>
|
|
The following environment variables affect the execution
|
|
of db_txn:
|
|
|
|
DB_HOME
|
|
If the dbenv argument to txn_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 txn_open, as
|
|
described in <B><A HREF="db_appinit.html">db_appinit(3)</A></B>.
|
|
|
|
TMPDIR
|
|
If the dbenv argument to txn_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
|
|
txn_open section above.
|
|
|
|
|
|
</PRE>
|
|
<H2>ERRORS</H2><PRE>
|
|
The txn_open function may fail and return errno for any of
|
|
the errors specified for the following DB and library
|
|
functions: <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><A HREF="db_txn.html">txn_unlink(3)</A></B>, <B>unlink(2)</B>, and <B>write(2)</B>.
|
|
|
|
In addition, the txn_open function may fail and return
|
|
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 txn_begin function may fail and return errno for any
|
|
of the errors specified for the following DB and library
|
|
functions: <B>fcntl(2)</B>, <B>fflush(3)</B>, <B><A HREF="db_log.html">log_put(3)</A></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 txn_begin function may fail and return
|
|
errno for the following conditions:
|
|
|
|
[ENOSPC]
|
|
The maximum number of concurrent transactions has
|
|
been reached.
|
|
|
|
The txn_prepare function may fail and return errno for any
|
|
of the errors specified for the following DB and library
|
|
functions: <B>fcntl(2)</B>, <B>fflush(3)</B>, <B><A HREF="db_log.html">log_flush(3)</A></B>, and
|
|
<B>strerror(3)</B>.
|
|
|
|
The txn_commit function may fail and return errno for any
|
|
of the errors specified for the following DB and library
|
|
functions: <B>fcntl(2)</B>, <B>fflush(3)</B>, <B><A HREF="db_lock.html">lock_vec(3)</A></B>, <B><A HREF="db_log.html">log_put(3)</A></B>,
|
|
<B>malloc(3)</B>, <B>memcpy(3)</B>, and <B>strerror(3)</B>.
|
|
|
|
In addition, the txn_commit function may fail and return
|
|
errno for the following conditions:
|
|
|
|
[EINVAL]
|
|
The transaction was aborted.
|
|
|
|
The txn_abort function may fail and return errno for any
|
|
of the errors specified for the following DB and library
|
|
functions: <B><A HREF="db_txn.html">DBenv->tx_recover(3)</A></B>, <B>fcntl(2)</B>, <B>fflush(3)</B>,
|
|
<B><A HREF="db_lock.html">lock_vec(3)</A></B>, <B><A HREF="db_log.html">log_get(3)</A></B>, <B>memset(3)</B>, and <B>strerror(3)</B>.
|
|
|
|
[EINVAL]
|
|
The transaction was already aborted.
|
|
|
|
The txn_checkpoint function may fail and return errno for
|
|
any of the errors specified for the following DB and
|
|
library functions: <B>fcntl(2)</B>, <B>fflush(3)</B>, <B><A HREF="db_log.html">log_compare(3)</A></B>,
|
|
<B><A HREF="db_log.html">log_put(3)</A></B>, <B>malloc(3)</B>, <B>memcpy(3)</B>, <B><A HREF="db_mpool.html">memp_sync(3)</A></B>, <B>memset(3)</B>,
|
|
<B>strerror(3)</B>, and <B>time(3)</B>.
|
|
|
|
[EINVAL]
|
|
An invalid flag value or parameter was specified.
|
|
|
|
The txn_close function may fail and return errno 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><A HREF="db_log.html">log_flush(3)</A></B>,
|
|
<B>munmap(2)</B>, <B>strerror(3)</B>, and <B><A HREF="db_txn.html">txn_abort(3)</A></B>.
|
|
|
|
The txn_unlink function may fail and return errno 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 txn_unlink function may fail and return
|
|
errno for the following conditions:
|
|
|
|
[EBUSY]
|
|
The shared memory region was in use and the force
|
|
flag was not set.
|
|
|
|
The txn_stat function may fail and return errno 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_appinit.html">db_appinit(3)</A></B>, <B><A HREF="db_cursor.html">db_cursor(3)</A></B>, <B><A HREF="db_dbm.html">db_dbm(3)</A></B>, <B><A HREF="db_internal.html">db_internal(3)</A></B>,
|
|
<B><A HREF="db_lock.html">db_lock(3)</A></B>, <B><A HREF="db_log.html">db_log(3)</A></B>, <B><A HREF="db_mpool.html">db_mpool(3)</A></B>, <B><A HREF="db_open.html">db_open(3)</A></B>, <B><A HREF="db_thread.html">db_thread(3)</A></B>,
|
|
<B><A HREF="db_txn.html">db_txn(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>
|