mirror of
https://github.com/mozilla/gecko-dev.git
synced 2024-11-08 04:27:37 +00:00
440 lines
21 KiB
HTML
440 lines
21 KiB
HTML
<HTML>
|
|
<HEAD>
|
|
<TITLE>DbLockTab</TITLE>
|
|
</HEAD>
|
|
<BODY BGCOLOR=white>
|
|
<H1>DbLockTab</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>void</B> <B>close()</B>
|
|
<B>throws</B> <B>DbException;</B>
|
|
|
|
<B>public</B> <B>void</B> <B>detect(int</B> <B>flags,</B> <B>int</B> <B>atype)</B>
|
|
<B>throws</B> <B>DbException;</B>
|
|
|
|
<B>public</B> <B>DbLock</B> <B>get(int</B> <B>locker,</B> <B>int</B> <B>flags,</B> <B>Dbt</B> <B>obj,</B> <B>int</B> <B>lock</B>_<B>mode)</B>
|
|
<B>throws</B> <B>DbException;</B>
|
|
|
|
<B>public</B> <B>int</B> <B>id()</B>
|
|
<B>throws</B> <B>DbException;</B>
|
|
|
|
<B>public</B> <B>static</B> <B>DbLockTab</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>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>
|
|
|
|
|
|
</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
|
|
locking interface.
|
|
|
|
The DbLockTab class is intended to provide general-purpose
|
|
locking. While designed to work with the other Db
|
|
classes, this class is also useful for more general
|
|
locking purposes. Locks can be shared between processes.
|
|
In most cases, when multiple treads or processes are using
|
|
locking, the deadlock detector, <B><A HREF="db_deadlock.html">db_deadlock(1)</A></B>, should be
|
|
run.
|
|
|
|
The vec method (as it appears in the C and C++ APIs) is
|
|
not yet implemented for Java and so it not described.
|
|
However, understanding this function in the C or C++ API
|
|
is helpful in understanding the get method, so please
|
|
refer to lock_vec in <B><A HREF="db_lock.html">db_lock(3)</A></B>.
|
|
|
|
DbLockTab.open
|
|
The DbLockTab.open method returns a lock table identified
|
|
by the <B>directory</B> dir.
|
|
|
|
If the dbenv argument to DbLockTab.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, lock table 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 lock table are created in
|
|
this directory. This directory must already exist when
|
|
DbLockTab.open is called. If the lock table already
|
|
exists, the process must have permission to read and write
|
|
the existing files. If the lock table 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 DbLockTab handle returned by the
|
|
DbLockTab.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.
|
|
|
|
All files created by the lock 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 locking 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 DbLockTab.open are described below. As
|
|
references to the DbEnv object may be maintained by
|
|
DbLockTab.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 DbLockTab.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>.
|
|
|
|
byte[][] lk_conflicts;
|
|
A lk_modes by lk_modes array. A non-0 value for the
|
|
array element:
|
|
|
|
lk_conflicts[requested_mode][held_mode]
|
|
|
|
indicates that requested_mode and held_mode conflict.
|
|
The ``not-granted'' mode must be represented by 0.
|
|
If lk_conflicts is null, the conflicts array
|
|
db_rw_conflicts is used; see the section below
|
|
entitled ``STANDARD LOCK MODES'' for a description of
|
|
that array.
|
|
|
|
int lk_detect;
|
|
If non-0, specifies that the deadlock detector be run
|
|
whenever a lock conflict occurs, and specifies which
|
|
transaction should be aborted in the case of a
|
|
deadlock. The lk_detect field must be set to one of
|
|
the following values.
|
|
|
|
Db.DB_LOCK_DEFAULT
|
|
Use the default policy as specified in the
|
|
<B><A HREF="db_deadlock.html">db_deadlock(1)</A></B> man page.
|
|
|
|
Db.DB_LOCK_OLDEST
|
|
Abort the oldest transaction.
|
|
|
|
Db.DB_LOCK_RANDOM
|
|
Abort a random transaction involved in the
|
|
deadlock.
|
|
|
|
Db.DB_LOCK_YOUNGEST
|
|
Abort the youngest transaction.
|
|
|
|
int lk_max;
|
|
The maximum number of locks to be held or requested
|
|
in the table. This value is used by DbLockTab.open
|
|
to estimate how much space to allocate for various
|
|
lock-table data structures. If lk_max is not
|
|
explicitly set, a default value is used.
|
|
|
|
int lk_modes;
|
|
|
|
The number of lock modes to be recognized by the lock
|
|
table (including
|
|
the ``not-granted'' mode). If lk_modes is 0, the
|
|
value DB_LOCK_RW_N is used; see below for a
|
|
description of that value.
|
|
|
|
The DbLockTab.open method throws a <B><A HREF="DbException.j.html">DbException(3)</A></B> that
|
|
encapsulates an errno on failure.
|
|
|
|
DbLockTab.id
|
|
The DbLockTab.id method returns a locker ID, which is
|
|
guaranteed to be unique in the specified lock table.
|
|
|
|
The access methods (see Db.open in <B><A HREF="Db.j.html">Db(3)</A></B>), generate a
|
|
unique locker ID for each file that is opened with
|
|
locking. During Db access method operation, this locker
|
|
ID will be used for all lock calls unless a transaction
|
|
identifier was specified for the call, in which case the
|
|
transaction ID specified is used for locking.
|
|
|
|
The DbLockTab.id method throws a <B><A HREF="DbException.j.html">DbException(3)</A></B> that
|
|
encapsulates an errno on failure.
|
|
|
|
DbLockTab.get
|
|
The DbLockTab.get method gets a lock, as defined by the
|
|
values of locker, obj and mode. The locker argument is an
|
|
unsigned 32-bit integer quantity. It represents the
|
|
entity requesting or releasing the lock.
|
|
|
|
The flags value must be set to 0 or the following value:
|
|
|
|
Db.DB_LOCK_NOWAIT
|
|
If a lock cannot be granted because the requested
|
|
lock conflicts with an existing lock, return
|
|
immediately instead of waiting for the lock to become
|
|
available.
|
|
|
|
A reference to the acquired lock is returned. (This
|
|
reference is invalidated by any call to DbLock.put that
|
|
releases the lock.) See <B><A HREF="DbLock.j.html">DbLock(3)</A></B>.
|
|
|
|
DbLockTab.close
|
|
The DbLockTab.close method disassociates the calling
|
|
process from the lock table. The object should not be
|
|
used after a call to close. Note that DbLockTab.close
|
|
does not release any locks still held by the closing
|
|
process. (This provides functionality for long-lived
|
|
locks.)
|
|
|
|
In addition, if the dir argument to DbLockTab.open was
|
|
null and dbenv was not initialized using DbEnv.appinit,
|
|
all files created for this shared region will be removed,
|
|
as if DbLockTab.unlink were called.
|
|
|
|
When multiple threads are using the DbLockTab object
|
|
concurrently, only a single thread may call the
|
|
DbLockTab.close method.
|
|
|
|
The DbLockTab.close method throws a <B><A HREF="DbException.j.html">DbException(3)</A></B> that
|
|
encapsulates an errno on failure.
|
|
|
|
DbLockTab.unlink
|
|
The DbLockTab.unlink method destroys the lock table
|
|
identified by the directory dir, removing all files used
|
|
to implement the lock table. (The directory dir is not
|
|
removed.) If there are processes that have called
|
|
DbLockTab.open without calling DbLockTab.close (i.e.,
|
|
there are processes currently using the lock table),
|
|
DbLockTab.unlink will fail without further action, unless
|
|
the force flag is set, in which case DbLockTab.unlink will
|
|
attempt to remove the lock table files regardless of any
|
|
processes still using the lock table.
|
|
|
|
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
|
|
lock table 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 lock table by
|
|
removing all of the files in the directory specified to
|
|
the DbLockTab.open method, as lock table files are never
|
|
created in any directory other than the one specified to
|
|
DbLockTab.open. Note, however, that this has the
|
|
potential to remove files created by the other DB
|
|
subsystems in this database environment.
|
|
|
|
The DbLockTab.unlink method throws a <B><A HREF="DbException.j.html">DbException(3)</A></B> that
|
|
encapsulates an errno on failure.
|
|
|
|
DbLockTab.detect
|
|
The DbLockTab.detect method runs one iteration of the
|
|
deadlock detector on the current lock table. The deadlock
|
|
detector traverses the lock table, detects deadlocks, and
|
|
if it finds one, marks one of the participating
|
|
transactions for abort and then returns.
|
|
|
|
The flags value is specified by <B>or</B>'ing together one or
|
|
more of the following values:
|
|
|
|
Db.DB_LOCK_CONFLICT
|
|
Only run the deadlock detector if a lock conflict has
|
|
occurred since the last time that the deadlock
|
|
detector was run.
|
|
|
|
The atype parameter specifies which transaction to abort
|
|
in the case of deadlock. It must be set to one of values
|
|
described above for the lk_detect field of the DbEnv
|
|
object.
|
|
|
|
The DbLockTab.detect method throws a <B><A HREF="DbException.j.html">DbException(3)</A></B> that
|
|
encapsulates an errno on failure.
|
|
|
|
The DbLockTab.detect method is based on the C lock_detect
|
|
function, which is the underlying function used by the
|
|
<B><A HREF="db_deadlock.html">db_deadlock(1)</A></B> utility. See the source code for the
|
|
db_deadlock utility for an example of using lock_detect in
|
|
a UNIX environment.
|
|
|
|
|
|
</PRE>
|
|
<H2>ENVIRONMENT VARIABLES</H2><PRE>
|
|
The following environment variables affect the execution
|
|
of db_lock:
|
|
|
|
DB_HOME
|
|
If the dbenv argument to DbLockTab.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 DbLockTab.open, as described in
|
|
<B><A HREF="db_appinit.html">db_appinit(3)</A></B>.
|
|
|
|
TMPDIR
|
|
If the dbenv argument to DbLockTab.open was null or
|
|
not initialized using db_appinit, the environment
|
|
variable TMPDIR may be used as the directory in which
|
|
to create the lock table, as described in the
|
|
DbLockTab.open section above.
|
|
|
|
|
|
</PRE>
|
|
<H2>STANDARD LOCK MODES</H2><PRE>
|
|
The DbLockTab class defines the following integer
|
|
constants, known elsewhere as db_lockmode_t, which which
|
|
specify the type of the lock mode used with the standard
|
|
tables above:
|
|
|
|
Db.DB_LOCK_NG
|
|
not granted (always 0)
|
|
|
|
Db.DB_LOCK_READ
|
|
read (shared)
|
|
|
|
Db.DB_LOCK_WRITE
|
|
write (exclusive)
|
|
|
|
|
|
</PRE>
|
|
<H2>ERRORS</H2><PRE>
|
|
The DbLockTab.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="DbLock.j.html">DbLock.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>unlink(2)</B>,
|
|
and <B>write(2)</B>.
|
|
|
|
In addition, the DbLockTab.open method may fail and throw
|
|
a <B><A HREF="DbException.j.html">DbException(3)</A></B> encapsulating an errno for the following
|
|
conditions:
|
|
|
|
[EAGAIN]
|
|
The shared memory region was locked and (repeatedly)
|
|
unavailable.
|
|
|
|
[EINVAL]
|
|
An invalid flag value or parameter was specified.
|
|
|
|
The DB_THREAD flag was specified and spinlocks are
|
|
not implemented for this architecture.
|
|
|
|
The DbLockTab.get 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="DbLock.j.html">DbLock.detect(3)</A></B>,
|
|
<B>fcntl(2)</B>, <B>fflush(3)</B>, <B>lseek(2)</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 DbLockTab.get 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 DbLockTab.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>close(2)</B>, <B>fcntl(2)</B>,
|
|
<B>fflush(3)</B>, <B>munmap(2)</B>, and <B>strerror(3)</B>.
|
|
|
|
The DbLockTab.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 DbLockTab.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 DbLockTab.detect 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>calloc(3)</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>.
|
|
|
|
|
|
</PRE>
|
|
<H2>BUGS</H2><PRE>
|
|
If a process dies while holding locks, those locks remain
|
|
held and are <B>never</B> released. In this case, all processes
|
|
should exit as quickly as possible, so that db_recover can
|
|
be run.
|
|
|
|
|
|
</PRE>
|
|
<H2>SEE ALSO</H2><PRE>
|
|
<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>
|