Berkeley DB Reference Guide: Locking Subsystem

Configuring locking: sizing the system

The lock system is sized using the following three functions:

DBENV->set_lk_max_locks
DBENV->set_lk_max_lockers
DBENV->set_lk_max_objects

The DBENV->set_lk_max_locks, DBENV->set_lk_max_lockers and DBENV->set_lk_max_objects functions specify, respectively, the maximum number of locks, lockers and locked objects supported by the lock subsystem. The maximum number of locks is the number of locks that can be simultaneously requested in the system. The maximum number of lockers is the number of lockers that can simultaneously request locks in the system. The maximum number of lock objects is the number of objects that can simultaneously be locked in the system. Selecting appropriate values requires an understanding of your application and its databases. If the values are too small, then requests for locks in an application will fail. If the values are too large, then the locking subsystem will consume more resources than is necessary. It is better to err in the direction of allocating too many locks, lockers and objects as increasing the number of locks does not require large amounts of additional resources.

The recommended algorithm for selecting the maximum number of locks, lockers and lock objects, is to run the application under stressful conditions and then review the lock system's statistics to determine the maximum number of locks, lockers and lock objects that were used. Then, double these values for safety. However, in some large applications, finer granularity of control is necessary in order to minimize the size of the lock subsystem.

The maximum number of lockers can be estimated as follows:

• If the database environment is configured to use transactions, then the maximum number of lockers needed is the number of simultaneously active transactions and child transactions (where a child transaction is active until its parent commits or aborts, not until it commits or aborts).
• If the database environment is not configured to use transactions, then the maximum number of lockers needed is the number of simultaneous non-cursor operations plus an additional locker for every simultaneously open cursor.

The maximum number of lock objects needed can be estimated as follows:

• For Btree and Recno access methods, you will need, at a minimum, one lock object per level of the database tree. (Unless keys are quite large with respect to the page size, neither Recno nor Btree database trees should ever be deeper than five levels.) Then, you will need one lock object for each leaf page of the database tree that will be simultaneously accessed.
• For the Queue access method you will need one lock object per record that is simultaneously accessed. To this, add one lock object per page that will be simultaneously accessed. (Since the Queue access method uses fixed-length records, and the database page size is known, it is possible to calculate the number of pages and therefore, lock objects, required.) Deleted records skipped by a DB_NEXT or DB_PREV operation do not require a separate lock object. Further, if your application is using transactions, then no database operation will ever use more than three lock objects at any time.
• For the Hash access method you only need a single lock object.

For all access methods, you should then add an additional lock object per database, for the database's metadata page.

The maximum number of locks required by an application cannot be easily estimated. It is possible to calculate a maximum number of locks by multiplying the maximum number of lockers, times the maximum number of lock objects, times two (two for the two possible lock modes for each object, read and write). However, this is a pessimal value, and real applications are unlikely to actually need that many locks. Review of the lock subsystem statistics is the best way to determine this value.

Copyright Sleepycat Software