#include <db_cxx.h>

int
DbEnv::lock_vec(u_int32_t locker, u_int32_t flags,
    DB_LOCKREQ list[], int nlist, DB_LOCKREQ **elistp);

Description

The DbEnv::lock_vec method atomically obtains and releases one or more locks from the lock table. The DbEnv::lock_vec method 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.

The locker argument specified to DbEnv::lock_vec 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_LOCK_NOWAIT

If a lock cannot be immediately granted because the requested lock conflicts with an existing lock, return instead of waiting for the lock to become available.

The list array provided to DbEnv::lock_vec is typedef'd as DB_LOCKREQ. A DB_LOCKREQ structure has at least the following fields, which must be initialized before calling DbEnv::lock_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 DbEnv::lock_vec, if the lock field is non-NULL, a reference to the acquired lock is stored there. (This reference is invalidated by any call to DbEnv::lock_vec or DbLock::put that releases the lock.)

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 DbEnv::lock_vec that appear after the DB_LOCK_PUT_ALL entry are not considered for this operation).

DB_LOCK_PUT_OBJ

All locks held on the object obj are released. The mode and locker parameters are ignored. Note that any locks acquired as a part of the current call to DbEnv::lock_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.

const lockmode_t mode;

The lock mode, used as an index into the environment's lock conflict array. See DbEnv::set_lk_conflicts and Standard Lock Modes for a description of that array.

DB_LOCK lock;

A lock reference.

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

If any of the requested locks cannot be acquired, or any of the locks to be released cannot be released, the operations before the failing operation are guaranteed to have completed successfully, and DbEnv::lock_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.

The DbEnv::lock_vec method may return or throw an exception encapsulating one of the following values:

DB_LOCK_NOTGRANTED

A lock was requested that could not be immediately granted and the flag parameter was set to DB_LOCK_NOWAIT. In this case, if non-NULL, elistp identifies the request that was not granted.

Otherwise, the DbEnv::lock_vec method either returns a non-zero error value or throws an exception that encapsulates a non-zero error value on failure, and returns 0 on success.

Errors

The DbEnv::lock_vec method may fail and throw an exception or return a non-zero error for the following conditions:

DB_LOCK_DEADLOCK

The operation was selected to resolve a deadlock.

EINVAL

An invalid flag value or parameter was specified.

ENOMEM

The maximum number of locks has been reached.

The DbEnv::lock_vec method may fail and throw an exception or return a non-zero error for errors specified for other Berkeley DB and C library or system methods. If a catastrophic error has occurred, the DbEnv::lock_vec method may fail and either return DB_RUNRECOVERY or throw an exception encapsulating DB_RUNRECOVERY, in which case all subsequent Berkeley DB calls will fail in the same way.

Classes

See Also