DbLockTab
NAME
DbLockTab - lock manager
SYNOPSIS
#include <db_cxx.h>
static int
DbLockTab::open(const char *dir,
int flags, int mode, DbEnv *dbenv, DbLockTab **regionp);
int
DbLockTab::id(u_int32_t *idp);
int
DbLockTab::vec(u_int32_t locker, int flags,
DB_LOCKREQ list[], int nlist, DB_LOCKREQ **elistp);
int
DbLockTab::get(u_int32_t locker, int flags,
const Dbt *obj, const db_lockmode_t lock_mode, DB_LOCK *lock);
int
DbLockTab::close();
static int
DbLockTab::unlink(const char *dir, int force, DbEnv *dbenv);
int
DbLockTab::detect(db_detect_t atype, int flags);
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
locking interface.
The DbLockTab class is intended to provide general-purpose
locking. While designed to work with the other Db func-
tions, 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 lock-
ing, the deadlock detector, db_deadlock(1), should be run.
DbLockTab::open
The DbLockTab::open method copies a pointer, to the lock
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 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 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 DbLockTab handle returned by the DbLock-
Tab::open method to be useable by multiple threads
within a single address space, i.e., to be ``free-
threaded''.
All files created by the lock 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 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 explic-
itly set will default to appropriate values.
The following fields in the DbEnv object may be initial-
ized, using the appropriate set method, before calling
DbLockTab::open:
void *(*db_errcall)(char *db_errpfx, char *buffer);
FILE *db_errfile;
const char *db_errpfx;
class ostream *db_error_stream;
If lk_conflicts is NULL, the conflicts array
db_rw_conflicts is used; see the section below enti-
tled ``STANDARD LOCK MODES'' for a description of
that array.
db_detect_t 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 dead-
lock. The lk_detect field must be set to one of the
following values.
DB_LOCK_DEFAULT
Use the default policy as specified in the
db_deadlock(1) man page.
DB_LOCK_OLDEST
Abort the oldest transaction.
DB_LOCK_RANDOM
Abort a random transaction involved in the dead-
lock.
DB_LOCK_YOUNGEST
Abort the youngest transaction.
unsigned 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 explic-
itly 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 DbException(3) or
returns the value of errno on failure and 0 on success.
DbLockTab::id
The DbLockTab::id method copies a locker ID, which is
guaranteed to be unique in the specified lock table, into
the memory location referenced by idp.
The access methods (see Db::open in Db(3)), generate a
unique locker ID for each file that is opened with lock-
ing. During Db access method operation, this locker ID
will be used for all lock calls unless a transaction iden-
tifier was specified for the call, in which case the
transaction ID specified is used for locking.
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_LOCK_NOWAIT
If a lock cannot be granted because the requested
lock conflicts with an existing lock, return immedi-
ately instead of waiting for the lock to become
available.
The list array provided to DbLockTab::vec is typedef'd in
<db_cxx.h> as DB_LOCKREQ. A DB_LOCKREQ structure has at
least the following fields, which must be initialized
before calling DbLockTab::vec:
lockop_t op;
The operation to be performed, which must be set to
one of the following values:
DB_LOCK_GET
Get a lock, as defined by the values of locker,
obj and mode. Upon return from DbLockTab::vec,
if the lock field is non-NULL, a reference to
the acquired lock is stored there. (This refer-
ence is invalidated by any call to DbLock-
Tab::vec or DbLock::put that releases the lock.)
See DbLock(3).
DB_LOCK_PUT
The lock referenced by the contents of the lock
field is released.
DB_LOCK_PUT_ALL
All locks held by the locker are released. (Any
locks acquired as a part of the current call to
DbLockTab::vec that appear after the
DB_LOCK_PUT_ALL entry are not considered for
this operation).
DB_LOCK_PUT_OBJ
All locks held by the locker, on the object obj,
with the mode specified by lock_mode, are
released. A lock_mode of DB_LOCK_NG indicates
that all locks on the object should be released.
Note that any locks acquired as a part of the
current call to DbLockTab::vec that occur before
the DB_LOCK_PUT_OBJ will also be released; those
acquired afterwards will not be released.
const Dbt obj;
An untyped byte string that specifies the object to
be locked or released.
tions before the failing operation are guaranteed to have
completed successfully, and DbLockTab::vec returns a non-
zero value. In addition, if elistp is not NULL, it is set
to point to the DB_LOCKREQ entry that was being processed
when the error occurred.
In the case of an error, DbLockTab::vec may return one of
the following values:
DB_LOCK_DEADLOCK
The specified locker was selected as a victim in
order to resolve a deadlock.
DB_LOCK_NOTHELD
The lock cannot be released, as it was not held by
the locker.
DB_LOCK_NOTGRANTED
A lock was requested that could not be granted and
the flag parameter was set to DB_LOCK_NOWAIT. In
this case, if non-NULL, elistp identifies the request
that was granted.
Otherwise, the DbLockTab::vec method throws a DbExcep-
tion(3) or returns the value of errno on failure and 0 on
success.
DbLockTab::get
The DbLockTab::get method is a simple interface to the
DbLockTab::vec functionality, and is equivalent to calling
the DbLockTab::vec method with the locker argument, elistp
and conflict arguments, and a single element list array,
for which the op field is DB_LOCK_GET, and the obj,
lock_mode and lock fields are represented by the arguments
of the same name. Note that the type of the obj argument
to DbLockTab::get is different from the obj element found
in the DB_LOCKREQ structure. The DbLockTab::get method
returns success and failure as described for the DbLock-
Tab::vec method.
DbLockTab::close
The DbLockTab::close method disassociates the calling pro-
cess 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.) Pro-
cesses that wish to have all their locks released can do
so by issuing the appropriate DbLockTab::vec call.
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.
removed.) If there are processes that have called DbLock-
Tab::open without calling DbLockTab::close (i.e., there
are processes currently using the lock table), DbLock-
Tab::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. Pro-
cesses 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 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
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 DbException(3) or
returns the value of errno on failure and 0 on success.
DbLockTab::detect
The DbLockTab::detect method runs one iteration of the
deadlock detector on the table represented by DbLockTab.
The deadlock detector traverses the lock table, detects
deadlocks, and if it finds one, marks one of the partici-
pating transactions for abort and then returns.
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 flags value is specified by or'ing together one or
more of the following values:
DB_LOCK_CONFLICT
Only run the deadlock detector if a lock conflict has
occurred since the last time that the deadlock detec-
tor was run.
DB_HOME
If the dbenv argument to DbLockTab::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 DbLock-
Tab::open, as described in db_appinit(3).
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 DbLock-
Tab::open section above.
STANDARD LOCK MODES
The include file <db_cxx.h> declares two commonly used
conflict arrays:
const u_int8_t db_lock_rw_conflicts[];
This is a conflict array for a simple scheme using
shared and exclusive lock modes.
const u_int8_t db_lock_riw_conflicts[];
This is a conflict array that involves various intent
lock modes (e.g., intent shared) that are used for
multigranularity locking.
Their associated sizes are DB_LOCK_RW_N and DB_LOCK_RIW_N.
In addition, the include file <db_cxx.h> defines the type
db_lockmode_t, which is the type of the lock modes used
with the standard tables above:
DB_LOCK_NG
not granted (always 0)
DB_LOCK_READ
read (shared)
DB_LOCK_WRITE
write (exclusive)
ERRORS
Methods marked as returning errno will, by default, throw
an exception that encapsulates the error information. The
default error behavior can be changed, see DbException(3).
The DbLockTab::open 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:
DbLock::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),
An invalid flag value or parameter was specified.
The DB_THREAD flag was specified and spinlocks are
not implemented for this architecture.
The DbLockTab::vec 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:
DbLock::detect(3), fcntl(2), fflush(3), lseek(2),
memcpy(3), memset(3), mmap(2), munmap(2), strerror(3), and
write(2).
In addition, the DbLockTab::vec method may fail and throw
a DbException(3) or return errno for the following condi-
tions:
[EACCES]
An attempt was made to release lock held by another
locker.
[EINVAL]
An invalid flag value or parameter was specified.
The DbLockTab::get 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:
DbLock::detect(3), fcntl(2), fflush(3), lseek(2),
memcpy(3), memset(3), mmap(2), munmap(2), strerror(3), and
write(2).
In addition, the DbLockTab::get 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 DbLockTab::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: close(2),
fcntl(2), fflush(3), munmap(2), and strerror(3).
The DbLockTab::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),
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 DbLockTab::unlink method may fail and
throw a DbException(3) or return errno for the following
conditions:
held and are never released. In this case, all processes
should exit as quickly as possible, so that db_recover can
be run.
SEE ALSO
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)