m4_comment([$Id: max.so,v 10.11 2006/01/05 16:51:59 bostic Exp $])m4_ref_title(Locking Subsystem,    Configuring locking: sizing the system,    sizing the @locking subsystem, lock/config, lock/stdmode)m4_p([dnlThe lock system is sized using the following three methods:])m4_indent([dnlm4_ref(dbenv_set_lk_max_locks)m4_ref(dbenv_set_lk_max_lockers)m4_ref(dbenv_set_lk_max_objects)])m4_p([dnlThe m4_ref(dbenv_set_lk_max_locks), m4_ref(dbenv_set_lk_max_lockers),and m4_refT(dbenv_set_lk_max_objects)s specify the maximum number oflocks, lockers, and locked objects supported by the lock subsystem,respectively.  The maximum number of locks is the number of locks thatcan be simultaneously requested in the system.  The maximum number oflockers is the number of lockers that can simultaneously request locksin the system.  The maximum number of lock objects is the number ofobjects that can simultaneously be locked in the system.  Selectingappropriate values requires an understanding of your application and itsdatabases.  If the values are too small, requests for locks in anapplication will fail.  If the values are too large, the lockingsubsystem will consume more resources than is necessary.  It is betterto err in the direction of allocating too many locks, lockers, andobjects because increasing the number of locks does not require largeamounts of additional resources.   The default values are 1000 ofeach type of object.])m4_p([dnlWhen configuring a m4_cam application, the number of lock objects neededis two per open database (one for the database lock, and one for thecursor lock when the m4_ref(DB_CDB_ALLDB) option is not specified).  Thenumber of locks needed is one per open database handle plus one persimultaneous cursor or non-cursor operation.])m4_p([dnlConfiguring a m4_tam application is more complicated.  The recommendedalgorithm for selecting the maximum number of locks, lockers, and lockobjects is to run the application under stressful conditions and thenreview the lock system's statistics to determine the maximum number oflocks, lockers, and lock objects that were used.  Then, double thesevalues for safety.  However, in some large applications, finergranularity of control is necessary in order to minimize the size of theLock subsystem.])m4_p([dnlThe maximum number of lockers can be estimated as follows:])m4_bulletbeginm4_bullet([dnlIf the database environment is using transactions, the maximum numberof lockers can be estimated by adding the number of simultaneouslyactive non-transactional cursors open database handles to the number ofsimultaneously active transactions and child transactions (where a childtransaction is active until it commits or aborts, not until its parentcommits or aborts).])m4_bullet([dnlIf the database environment is not using transactions, the maximumnumber of lockers can be estimated by adding the number ofsimultaneously active non-transactional cursors and open databasehandles to the number of simultaneous non-cursor operations.])m4_bulletendm4_p([dnlThe maximum number of lock objects needed for a single databaseoperation can be estimated as follows:])m4_bulletbeginm4_bullet([dnlFor Btree and Recno access methods, you will need one lock object perlevel of the database tree, at a minimum.  (Unless keys are quite largewith respect to the page size, neither Recno nor Btree database treesshould ever be deeper than five levels.)  Then, you will need one lockobject for each leaf page of the database tree that will besimultaneously accessed.])m4_bullet([dnlFor the Queue access method, you will need one lock object per recordthat is simultaneously accessed.  To this, add one lock object per pagethat will be simultaneously accessed.  (Because the Queue access methoduses fixed-length records and the database page size is known, it ispossible to calculate the number of pages -- and, therefore, the lockobjects -- required.)  Deleted records skipped by a m4_ref(DB_NEXT) orm4_ref(DB_PREV) operation do not require a separate lock object.Further, if your application is using transactions, no databaseoperation will ever use more than three lock objects at any time.])m4_bullet([dnlFor the Hash access method, you only need a single lock object.])m4_bulletendm4_p([dnlFor all access methods, you should then add an additional lock objectper database for the database's metadata page.])m4_p([dnlNote that transactions accumulate locks over the transaction lifetime,and the lock objects required by a single transaction is the total lockobjects required by all of the database operations in the transaction.However, a database page (or record, in the case of the Queue accessmethod), that is accessed multiple times within a transaction onlyrequires a single lock object for the entire transaction.])m4_p([dnlThe maximum number of locks required by an application cannot be easilyestimated.  It is possible to calculate a maximum number of locks bymultiplying the maximum number of lockers, times the maximum number oflock objects, times two (two for the two possible lock modes for eachobject, read and write).  However, this is a pessimal value, and realapplications are unlikely to actually need that many locks.  Reviewingthe Lock subsystem statistics is the best way to determine this value.])m4_page_footer