DB_LOCK(3)

NAME
db_lock - general purpose lock manager

SYNOPSIS
#include <db_lock.h>
int
lock_create(const char *path, mode_t mode,
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,
LOCK_REQ_T list[], int nlist, LOCK_REQ_T **elistp, DBT *conflict);
int
lock_get(LOCK_TABLE_T *lt, const DBT *locker,
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);

DESCRIPTION
specific details of the locking interface.

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.

The parameter lock_modes is the number of lock modes to be recognized by the lock table (including the ``not-granted'' mode). The parameter conflicts is an lock_modes by lock_modes array. A non-0 value for:

conflicts[requested_mode][held_mode]

indicates that requested_mode and held_mode conflict. The ``not-granted'' mode must be represented by 0.

The include file <db_lock.h> declares two commonly used conflict arrays:

int lock_sx_n;

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.

int lock_g_n;

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.

In addition, <db_lock.h> defines the following macros that name lock modes for use with the standard tables above:

    LOCK_IS
        intent shared

    LOCK_IX
        intent exclusive

    LOCK_NG
        not granted (always 0)

    LOCK_S
        shared

    LOCK_SIX
        shared/intent exclusive

    LOCK_X
        exclusive

Maxlocks is the maximum number of locks to be held or requested in the table, and is used by lock_create to estimate how much space to allocate for various lock-table data structures.

[lock table lock]

The function lock_vec atomically obtains and releases one or more locks from the designated table. The function 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.

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 lock_vec returns an error. The function lock_vec returns 0 on success. If an error occurs, lock_vec returns one of the following values. In addition, if elistp is not NULL, it is set to point to the LOCK_REQ_T entry which was being processed when the error occurred.

LOCK_GET_DEADLOCK
    The specified locker was selected as a victim in order to resolve a deadlock. In this case, if the conflict argument is non-NULL, it is set to reference the identity of a locker holding the lock referenced by elistp at the time the request was denied. (This identity resides in static memory and may be overwritten by subsequent calls to lock_vec).

LOCK_GET_ERROR
    An error occurred and the external variable errno has been set to indicate the error.

LOCK_GET_NOTHELD
    The lock cannot be released, as it was not held by the locker.

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 lock_vec to succeed.)

LOCK_GET_TIMEOUT
    A timeout argument was specified, and the requested locks were not available soon enough. In this case, if the conflict argument is non-NULL, it is set to reference the identity of a locker holding the lock referenced by elistp at the time the request was denied. (This identity resides in static memory and may be overwritten by subsequent calls to lock_vec).

The locker argument specified to lock_vec is a pointer to an untyped byte string which identifies the entity requesting or releasing the lock. If locker is NULL, the calling process' pid is used instead.

The timeout argument provided to lock_vec specifies a maximum interval to wait for the locks to be granted. If timeout is NULL, it is ignored, and lock_vec will not return until all of the locks are acquired or an error has occurred.

The list array provided to 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 lock_vec:

enum lockop op;
    The operation to be performed, which must be set to one of the following values:

    LOCK_GET
        Get a lock, as defined by the values of locker, obj and lock_mode. Upon return from lock_vec, if the lockp field is non-NULL, a reference to the acquired lock is stored there. (This reference is invalidated by any call to lock_vec or lock_put which releases the lock.)

    LOCK_PUT
        The lock referenced by the contents of the lockp field is released.

    LOCK_PUT_ALL
        All locks held by the locker are released. (Any locks acquired as a part of the current call to lock_vec are not considered for this operation).

    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 LOCK_NG indicates that all locks on the object should be released. (Any locks acquired as a part of the current call to lock_vec are not considered for this operation).

const DBT obj;
    An untyped byte string which specifies the object to be locked or released.

const lock_mode_t lock_mode;
    The lock mode, used as an index into lt's conflict array.

LOCK_T **lockp;
    A pointer to a pointer to a lock reference.

The nlist argument specifies the number of elements in the list array.

The function lock_get is a simple interface to the lock_vec functionality, and is equivalent to calling the lock_vec function with the lt and locker arguments, NULL timeout, elistp and conflict arguments, and a single element list array, for which the op field is LOCK_GET, and the obj, lock_mode and lockp fields are represented by the arguments of the same name. Note that the type of the obj argument to lock_get is different from the obj element found in the LOCK_REQ_T structure. The lock_get function returns success and failure as described for the lock_vec function.

The function lock_put is a simple interface to the lock_vec functionality, and is equivalent to calling the lock_vec function with a single element list array, for which the op field is LOCK_PUT and the lockp field is represented by the argument of the same name. Note that the type of the lockp argument to lock_put is different from the lockp element found in the LOCK_REQ_T structure. The lock_put function returns success and failure as described for the lock_vec function.

The function lock_close disassociates the calling process from the lock table lt, after releasing all locks held or requested by that process.

ERRORS
The lock_create function may fail and set errno for any of the errors specified for the library routines mmap(2), open(2) and malloc(3).

The lock_open function may fail and set errno for any of the errors specified for the library routine mmap(2) and open(2).

The lock_close function may fail and set errno for any of the errors specified for the library routine close(2) and munmap(2).

The lock_unlink function may fail and set errno for any of the errors specified for the library function unlink(2) or the following:

[EBUSY]
    The lock table was in use and the force flag was not set.

SEE ALSO
db_btree(3), db_hash(3), db_log(3), db_mpool(3), db_open(3), db_recno(3), db_txn(3)

BUGS
The maxlocks parameter is a kluge, and should be deleted in favor of dynamically expanding the lock table.