Berkeley DB: lock_vec
Description: Berkeley DB: An embedded database programmatic toolkit.
Keywords: embedded,database,programmatic,toolkit,b+tree,btr ee,hash,hashing,transaction,transactions,locking,logging,access method,access me thods,java,C,C++

# lock_vec

`

###

    #include <db.h>

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

# Description

The lock_vec function atomically obtains and releases one or more locks from the lock table. The lock_vec function 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 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 granted because the requested lock conflicts with an existing lock, return immediately instead of waiting for the lock to become available.

The list array provided to lock_vec is typedef'd as DB_LOCKREQ. A DB_LOCKREQ structure has at least the following fields, which must be initialized before calling 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 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 lock_vec or lock_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 lock_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 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 lt's conflict 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 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.

In the case of an error, lock_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 lock_vec function returns the value of errno on failure, and 0 on success.

# Errors

If a fatal error occurs in Berkeley DB, the lock_vec function may fail and return DB_RUNRECOVERY, at which point all subsequent database calls will also return DB_RUNRECOVERY.

The lock_vec function may fail and return errno for any of the errors specified for the following Berkeley DB and C library functions: abort(3), fcntl(3), fflush(3), fprintf(3), fsync(3), getpid(3), isprint(3), lock_detect, lseek(3), memcpy(3), memset(3), mmap(3), munmap(3), printf(3), pstat_getdynamic(3), shmat(3), shmdt(3), strerror(3), sysconf(3), vfprintf(3), vsnprintf(3), and write(3).

In addition, the lock_vec function may fail and return errno for the following conditions:

EACCES
  An attempt was made to release lock held by another locker.

EINVAL
  An invalid flag value or parameter was specified.

# See Also

lock_close, lock_detect, lock_get, lock_id, lock_open, lock_put, lock_stat, lock_unlink and lock_vec.`