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([dnl
The lock system is sized using the following three methods:])

m4_indent([dnl
m4_ref(dbenv_set_lk_max_locks)
m4_ref(dbenv_set_lk_max_lockers)
m4_ref(dbenv_set_lk_max_objects)])

m4_p([dnl
The 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 of
locks, lockers, and locked objects supported by the lock subsystem,
respectively.  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, requests for locks in an
application will fail.  If the values are too large, 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 because increasing the number of locks does not require large
amounts of additional resources.   The default values are 1000 of
each type of object.])

m4_p([dnl
When configuring a m4_cam application, the number of lock objects needed
is two per open database (one for the database lock, and one for the
cursor lock when the m4_ref(DB_CDB_ALLDB) option is not specified).  The
number of locks needed is one per open database handle plus one per
simultaneous cursor or non-cursor operation.])

m4_p([dnl
Configuring a m4_tam application is more complicated.  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.])

m4_p([dnl
The maximum number of lockers can be estimated as follows:])

m4_bulletbegin
m4_bullet([dnl
If the database environment is using transactions, the maximum number
of lockers can be estimated by adding the number of simultaneously
active non-transactional cursors open database handles to the number of
simultaneously active transactions and child transactions (where a child
transaction is active until it commits or aborts, not until its parent
commits or aborts).])
m4_bullet([dnl
If the database environment is not using transactions, the maximum
number of lockers can be estimated by adding the number of
simultaneously active non-transactional cursors and open database
handles to the number of simultaneous non-cursor operations.])
m4_bulletend

m4_p([dnl
The maximum number of lock objects needed for a single database
operation can be estimated as follows:])
m4_bulletbegin
m4_bullet([dnl
For Btree and Recno access methods, you will need one lock object per
level of the database tree, at a minimum.  (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.])
m4_bullet([dnl
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.  (Because 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, the lock
objects -- required.)  Deleted records skipped by a m4_ref(DB_NEXT) or
m4_ref(DB_PREV) operation do not require a separate lock object.
Further, if your application is using transactions, no database
operation will ever use more than three lock objects at any time.])
m4_bullet([dnl
For the Hash access method, you only need a single lock object.])
m4_bulletend

m4_p([dnl
For all access methods, you should then add an additional lock object
per database for the database's metadata page.])

m4_p([dnl
Note that transactions accumulate locks over the transaction lifetime,
and the lock objects required by a single transaction is the total lock
objects required by all of the database operations in the transaction.
However, a database page (or record, in the case of the Queue access
method), that is accessed multiple times within a transaction only
requires a single lock object for the entire transaction.])

m4_p([dnl
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.  Reviewing
the Lock subsystem statistics is the best way to determine this value.])

m4_page_footer