path: root/src/plugins/kdb/db2/libdb2/man/db_lock.3

.\" Copyright (c) 1994, 1995
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)db_lock.3	8.14 (Berkeley) 8/1/95
.\"
.TH DB_LOCK 3 "August 1, 1995"
.UC 7
.SH NAME
db_lock \- general purpose lock manager
.SH SYNOPSIS
.nf
.ft B
#include <db_lock.h>

int
lock_create(const char *path, mode_t mode,
.ti +5
int lock_modes, const int8_t conflicts[][], u_int maxlocks);

LOCK_TABLE_T *
lock_open(const char *path);

int
lock_vec(LOCK_TABLE_T *lt, DBT *locker, struct timespec *timeout,
.ti +5
LOCK_REQ_T list[], int nlist, LOCK_REQ_T **elistp, DBT *conflict);

int
lock_get(LOCK_TABLE_T *lt, const DBT *locker,
.ti +5
const DBT *obj, const lock_mode_t lock_mode, LOCK_T **lockp);

int
lock_put(LOCK_T *lockp);

int
lock_close(LOCK_TABLE_T *lt);

int
lock_unlink(const char *path, int force);
.ft R
.fi
.SH DESCRIPTION
.so db.so
.GN
specific details of the locking interface.
.PP
.I Db_lock
is the library interface intended to provide general-purpose locking. 
While designed to work with the other DB functions, these functions are
also useful for more general locking purposes.
Locks can be shared between processes.
.PP
.CR "lock table" lock
.PP
The parameter
.I lock_modes
is the number of lock modes to be recognized by the lock table
(including the ``not-granted'' mode).
The parameter
.I conflicts
is an
.I lock_modes
by
.I lock_modes
array.
A non-0 value for:
.sp
.ti +5
conflicts[requested_mode][held_mode]
.sp
indicates that
.I requested_mode
and
.I held_mode
conflict.
The ``not-granted'' mode must be represented by 0.
.PP
The include file <db_lock.h> declares two commonly used conflict arrays:
.TP 5
int lock_sx_n;
.br
.ns
.TP 5
const int8_t lock_sx_c[lock_sx_n][lock_sx_n];
These variables specify a conflict array
for a simple scheme using shared and exclusive lock modes.
.TP 5
int lock_g_n;
.br
.ns
.TP 5
const int8_t lock_g_c[lock_g_n][lock_g_n];
These variables specify a conflict array that involves various intent
lock modes (e.g. intent shared) that are used for multigranularity locking.
.PP
In addition,
<db_lock.h> defines the following macros that name lock modes for use with
the standard tables above:
.RS
.TP 5
LOCK_IS
intent shared
.br
.ns
.TP 5
LOCK_IX
intent exclusive
.br
.ns
.TP 5
LOCK_NG
not granted (always 0)
.br
.ns
.TP 5
LOCK_S
shared
.br
.ns
.TP 5
LOCK_SIX
shared/intent exclusive
.br
.ns
.TP 5
LOCK_X
exclusive
.RE
.PP
.I Maxlocks
is the maximum number of locks to be held or requested in the table,
and is used by
.I lock_create
to estimate how much space to allocate for various lock-table data
structures.
.PP
.RT lock_create
.PP
.OP "lock table" lock
.PP
The function
.I lock_vec
atomically obtains and releases one or more locks from the designated
table.
The function
.I lock_vec
is intended to support acquisition or trading of multiple locks
under one lock table semaphore, as is needed for lock coupling or
in multigranularity locking for lock escalation.
.PP
If any of the requested locks cannot be acquired
or any of the locks to be released cannot be released,
no locks are acquired and no locks are released, and
.I lock_vec
returns an error.
The function
.I lock_vec
returns 0 on success.
If an error occurs,
.I lock_vec
returns one of the following values.
In addition, if
.I elistp
is not NULL, it is set to point to the LOCK_REQ_T entry which
was being processed when the error occurred.
.TP 5
LOCK_GET_DEADLOCK
The specified
.I locker
was selected as a victim in order to resolve a deadlock.
In this case, if the
.I conflict
argument is non-NULL, it is set to reference the identity of a
locker holding the lock referenced by
.I elistp
at the time the request was denied.
(This identity resides in static memory and may be overwritten by
subsequent calls to
.IR lock_vec ).
.TP 5
LOCK_GET_ERROR
An error occurred and the external variable
.I errno
has been set to indicate the error.
.TP 5
LOCK_GET_NOTHELD
The lock cannot be released, as it was not held by the
.IR locker .
.TP 5
LOCK_GET_RESOURCE
The lock manager is unable to grant the requested locks because of
limited internal resources.
(Releasing locks may allow future calls to
.I lock_vec
to succeed.)
.TP 5
LOCK_GET_TIMEOUT
A timeout argument was specified, and the requested locks were not
available soon enough.
In this case, if the
.I conflict
argument is non-NULL, it is set to reference the identity of a
locker holding the lock referenced by
.I elistp
at the time the request was denied.
(This identity resides in static memory and may be overwritten by
subsequent calls to
.IR lock_vec ).
.PP
The
.I locker
argument specified to
.I lock_vec
is a pointer to an untyped byte string which identifies the entity
requesting or releasing the lock.
If
.I locker
is NULL, the calling process' pid is used instead.
.PP
The
.I timeout
argument provided to
.I lock_vec
specifies a maximum interval to wait for the locks to be granted.
If
.I timeout
is NULL, it is ignored, and
.I lock_vec
will not return until all of the locks are acquired or an error has
occurred.
.PP
The
.I list
array provided to 
.I lock_vec
is typedef'd in <db_lock.h> as LOCK_REQ_T.
A LOCK_REQ_T structure has at least the following fields,
which must be initialized before calling
.IR lock_vec :
.TP 5
enum lockop op;
The operation to be performed, which must be set to one of the
following values:
.RS
.TP 5
LOCK_GET
Get a lock, as defined by the values of
.IR locker ,
.I obj
and
.IR lock_mode .
Upon return from
.IR lock_vec ,
if the
.I lockp
field is non-NULL, a reference to the acquired lock is stored there.
(This reference is invalidated by any call to
.I lock_vec
or
.I lock_put
which releases the lock.)
.TP 5
LOCK_PUT
The lock referenced by the contents of the
.I lockp
field is released.
.TP 5
LOCK_PUT_ALL
All locks held by the
.I locker
are released.
(Any locks acquired as a part of the current call to
.I lock_vec
are not considered for this operation).
.TP 5
LOCK_PUT_OBJ
All locks held by the
.IR locker ,
on the object
.IR obj ,
with the mode specified by
.IR lock_mode ,
are released.
A
.I lock_mode
of LOCK_NG indicates that all locks on the object should be released.
(Any locks acquired as a part of the current call to
.I lock_vec
are not considered for this operation).
.RE
.TP 5
const DBT obj;
An untyped byte string which specifies the object to be locked or
released.
.TP 5
const lock_mode_t lock_mode;
The lock mode, used as an index into
.IR lt 's
conflict array.
.TP 5
LOCK_T **lockp;
A pointer to a pointer to a lock reference.
.PP
The
.I nlist
argument specifies the number of elements in the
.I list
array.
.PP
The function
.I lock_get
is a simple interface to the
.I lock_vec
functionality, and is equivalent to calling the
.I lock_vec
function with the
.I lt
and
.I locker
arguments, NULL
.IR timeout , 
.I elistp
and
.I conflict
arguments, and a single element
.I list
array, for which the
.I op
field is LOCK_GET, and the
.IR obj ,
.I lock_mode
and
.I lockp
fields are represented by the arguments of the same name.
Note that the type of the
.I obj
argument to
.I lock_get
is different from the
.I obj
element found in the LOCK_REQ_T structure.
The
.I lock_get
function returns success and failure as described for the
.I lock_vec
function.
.PP
The function
.I lock_put
is a simple interface to the
.I lock_vec
functionality, and is equivalent to calling the
.I lock_vec 
function with a single element
.I list
array, for which the
.I op
field is LOCK_PUT and the
.I lockp
field is represented by the argument of the same name.
Note that the type of the
.I lockp
argument to
.I lock_put
is different from the
.I lockp
element found in the LOCK_REQ_T structure.
The
.I lock_put
function returns success and failure as described for the
.I lock_vec
function.
.PP
The function
.I lock_close
disassociates the calling process from the lock table
.IR lt ,
after releasing all locks held or requested by that process.
.RT lock_close
.PP
.UN "lock table" lock
.SH "ERRORS"
The
.I lock_create
function may fail and set
.I errno
for any of the errors specified for the library routines
.IR mmap (2),
.IR open (2)
and
.IR malloc (3).
.PP
The
.I lock_open
function may fail and set
.I errno
for any of the errors specified for the library routine
.IR mmap (2)
and
.IR open (2).
.PP
The
.I lock_close
function may fail and set
.I errno
for any of the errors specified for the library routine
.IR close (2)
and
.IR munmap (2).
.PP
The
.I lock_unlink
function may fail and set
.I errno
for any of the errors specified for the library function
.IR unlink (2)
or the following:
.TP 5
[EBUSY]
The lock table was in use and the force flag was not set.
.SH "SEE ALSO"
.IR db_btree (3),
.IR db_hash (3),
.IR db_log (3),
.IR db_mpool (3),
.IR db_open (3),
.IR db_recno (3),
.IR db_txn (3)
.SH BUGS
The
.I maxlocks
parameter is a kluge, and should be deleted in favor of dynamically
expanding the lock table.