###

Berkeley DB Reference Guide:
  Locking Subsystem

# Configuring locking

The lock system is configured using the following interfaces:

>     DBENV->set_lk_conflicts
>     DBENV->set_lk_detect
>     DBENV->set_lk_max

The DBENV->set_lk_max interface specifies the number of locks that will be allocated in the locking subsystem. If this number is too small, then requests for locks in an application will fail. If this number is too large, then the lock subsystem will consume more resources than is necessary. Selecting an appropriate value requires an understanding of your application and its databases.

For Btree and Recno access methods, you will need, at a minimum, one lock per level of the tree. Unless keys are quite large or pages are quite small, neither Recno nor Btree files should be deeper than five levels. You may also need an additional lock for the Btree/Recno metadata page. The Hash access method never requires more than two locks.

For the Queue access method you will need one lock per record accessed by a transaction plus one page lock. Note that deleted records that are skipped by a DB_NEXT or DB_PREV operation are not locked. If you are not using transactions then an operation will never use more than three locks at a time.

In addition, for all access methods, you should assume one lock for every open cursor.

To estimate the number of locks required for an application, estimate the maximum number of locks needed per transaction (if running with transactions) or operation (if running without transactions). Multiply this number by the maximum number of concurrent threads and processes you expect your application to support. Then, for good measure, double this estimate.

The DBENV->set_lk_detect function specifies that the deadlock detector should be run whenever a lock blocks. This option provides for rapid detection of deadlocks at the expense of potentially frequent invocations of the deadlock detector. On a fast processor with a highly contentious application, where response time is critical, this is a good choice. An argument to the DBENV->set_lk_detect function indicates which transaction to abort when a deadlock is detected. It can take on any one of the following values:

DB_LOCK_YOUNGEST
  Abort the most recently started transaction.
DB_LOCK_OLDEST
  Abort the longest lived transaction.
DB_LOCK_RANDOM
  Abort whatever transaction the deadlock detector happens to find first.
DB_LOCK_DEFAULT
  Use the default policy (currently DB_RANDOM).

In general, DB_LOCK_DEFAULT is probably the correct choice. If an application has long-running transactions, then DB_LOCK_YOUNGEST will guarantee that transactions eventually complete, but it may do so at the expense of a large number of aborts.

The DBENV->set_lk_conflicts function allows you to specify your own locking conflicts matrix. This is an advanced configuration option, and rarely necessary.

Copyright Sleepycat Software