m4_comment([$Id: timeout.so,v 1.9 2005/12/02 17:27:49 alanb Exp $])m4_ref_title(Locking Subsystem,    Deadlock detection using timers,    [lock @timeouts, transaction @timeouts], lock/dead, lock/deaddbg)m4_p([dnlLock and transaction timeouts may be used in place of, or in additionto, regular deadlock detection.  If lock timeouts are set, lock requestswill return m4_ref(DB_LOCK_NOTGRANTED) from a lock call when it isdetected that the lock's timeout has expired, that is, the lock requesthas blocked, waiting, longer than the specified timeout.  If transactiontimeouts are set, lock requests will return m4_ref(DB_LOCK_NOTGRANTED)from a lock call when it has been detected that the transaction has beenactive longer than the specified timeout.])m4_p([dnlIf lock or transaction timeouts have been set, database operations willreturn m4_ref(DB_LOCK_DEADLOCK) when the lock timeout has expired or thetransaction has been active longer than the specified timeout.Applications wanting to distinguish between true deadlock and timeoutcan use the m4_ref(DB_TIME_NOTGRANTED) configuration flag, which causesdatabase operations to instead return m4_ref(DB_LOCK_NOTGRANTED) in thecase of timeout.])m4_p([dnlAs lock and transaction timeouts are only checked when lock requestsfirst block or when deadlock detection is performed, the accuracy ofthe timeout depends on how often deadlock detection is performed.  Morespecifically, transactions will continue to run after their timeout hasexpired if they do not block on a lock request after that time.A separate deadlock detection thread (or process) should alwaysbe used if the application depends on timeouts; otherwise, ifthere are no new blocked lock requests a pending timeout willnever trigger.])m4_p([dnlIf the database environment deadlock detector has been configured withthe m4_ref(DB_LOCK_EXPIRE) option, timeouts are the only mechanism bywhich deadlocks will be broken.  If the deadlock detector has beenconfigured with a different option, then regular deadlock detection willbe performed, and in addition, if timeouts have also been specified,lock requests and transactions will time out as well.])m4_p([dnlLock and transaction timeouts may be specified on a database environmentwide basis using the m4_refT(dbenv_set_timeout).  Lock timeouts may bespecified on a per-lock request basis using the m4_refT(lock_vec).  Lockand transaction timeouts may be specified on a per-transaction basisusing the m4_refT(txn_set_timeout).  Per-lock and per-transactiontimeouts supersede environment wide timeouts.])m4_p([dnlFor example, consider that the environment wide transaction timeout hasbeen set to 20ms, the environment wide lock timeout has been set to10ms, a transaction has been created in this environment and its timeoutvalue set to 8ms, and a specific lock request has been made on behalfof this transaction where the lock timeout was set to 4ms.  By default,transactions in this environment will be timed out if they block waitingfor a lock after 20ms.  The specific transaction described will be timedout if it blocks waiting for a lock after 8ms.  By default, any lockrequest in this system will be timed out if it blocks longer than 10ms,and the specific lock described will be timed out if it blocks longerthan 4ms.])m4_page_footer