###

Berkeley DB Reference Guide:
  Locking Subsystem

### Introduction to the locking subsystem

The locking subsystem provides interprocess and intraprocess concurrency control mechanisms. Although the lock system is used extensively by the Berkeley DB access methods and transaction system, it may also be used as a standalone subsystem to provide concurrency control to any set of designated resources.

The Lock subsystem is created, initialized, and opened by calls to DB_ENV->open with the DB_INIT_LOCK or DB_INIT_CDB flags specified.

The DB_ENV->lock_vec method is used to acquire and release locks. The DB_ENV->lock_vec method performs any number of lock operations atomically. It also provides the capability to release all locks held by a particular locker and release all the locks on a particular object. (Performing multiple lock operations atomically is useful in performing Btree traversals -- you want to acquire a lock on a child page and once acquired, immediately release the lock on its parent. This is traditionally referred to as lock-coupling). Two additional methods, DB_ENV->lock_get and DB_ENV->lock_put, are provided. These methods are simpler front-ends to the DB_ENV->lock_vec functionality, where DB_ENV->lock_get acquires a lock, and DB_ENV->lock_put releases a lock that was acquired using DB_ENV->lock_get or DB_ENV->lock_vec. All locks explicitly requested by an application should be released via calls to DB_ENV->lock_put or DB_ENV->lock_vec. Using DB_ENV->lock_vec instead of separate calls to DB_ENV->lock_put and DB_ENV->lock_get also reduces the synchronization overhead between multiple threads or processes. The three methods are fully compatible, and may be used interchangeably.

Applications must specify lockers and lock objects appropriately. When used with the Berkeley DB access methods, lockers and objects are handled completely internally, but an application using the lock manager directly must either use the same conventions as the access methods or define its own convention to which it adheres. If an application is using the access methods with locking at the same time that it is calling the lock manager directly, the application must follow a convention that is compatible with the access methods' use of the locking subsystem. See Access method locking conventions for more information.

The DB_ENV->lock_id function returns a unique ID that may safely be used as the locker parameter to the DB_ENV->lock_vec method. The access methods use DB_ENV->lock_id to generate unique lockers for the cursors associated with a database.

The DB_ENV->lock_detect function provides the programmatic interface to the Berkeley DB deadlock detector. Whenever two threads of control issue lock requests concurrently, the possibility for deadlock arises. A deadlock occurs when two or more threads of control are blocked, waiting for actions that another one of the blocked threads must take. For example, assume that threads A and B have each obtained read locks on object X. Now suppose that both threads want to obtain write locks on object X. Neither thread can be granted its write lock (because of the other thread's read lock). Both threads block and will never unblock because the event for which they are waiting can never happen.

The deadlock detector examines all the locks held in the environment, and identifies situations where no thread can make forward progress. It then selects one of the participants in the deadlock (according to the argument that was specified to DB_ENV->set_lk_detect), and forces it to return the value DB_LOCK_DEADLOCK, which indicates that a deadlock occurred. The thread receiving such an error must release all of its locks and undo any incomplete modifications to the locked resource. Locks are typically released, and modifications undone, by closing any cursors involved in the operation and aborting any transaction enclosing the operation. The operation may optionally be retried.

The DB_ENV->lock_stat function returns information about the status of the lock subsystem. It is the programmatic interface used by the db_stat utility.

The locking subsystem is closed by the call to DB_ENV->close.

Finally, the entire locking subsystem may be discarded using the DB_ENV->remove method.

Locking Subsystem and Related Methods | Description
--- | ---
DB_ENV->lock_detect | Perform deadlock detection
DB_ENV->lock_get | Acquire a lock
DB_ENV->lock_id | Acquire a locker ID
DB_ENV->lock_id_free | Release a locker ID
DB_ENV->lock_put | Release a lock
DB_ENV->lock_stat | Return lock subsystem statistics
DB_ENV->lock_vec | Acquire/release locks
DB_ENV->cdsgroup_begin | Get a locker ID in Berkeley DB Concurrent Data Store
Locking Subsystem Configuration |
DB_ENV->set_lk_conflicts | Set lock conflicts matrix
DB_ENV->set_lk_detect | Set automatic deadlock detection
DB_ENV->set_lk_max_lockers | Set maximum number of lockers
DB_ENV->set_lk_max_locks | Set maximum number of locks
DB_ENV->set_lk_max_objects | Set maximum number of lock objects
DB_ENV->set_timeout | Set lock and transaction timeout

Copyright (c) 1996,2007 Oracle. All rights reserved.