m4_comment([$Id: intro.so,v 10.27 2006/11/13 18:05:02 bostic Exp $])m4_ref_title(Locking Subsystem,    Introduction to the locking subsystem,    introduction to the @locking subsystem, program/faq, lock/config)m4_p([dnlThe locking subsystem provides interprocess and intraprocess concurrencycontrol mechanisms.  Although the lock system is used extensively bythe m4_db access methods and transaction system, it may also be used asa standalone subsystem to provide concurrency control to any set ofdesignated resources.])m4_p([dnlThe Lock subsystem is created, initialized, and opened by calls tom4_ref(dbenv_open) with the m4_ref(DB_INIT_LOCK) or m4_ref(DB_INIT_CDB)flags specified.])m4_p([dnlThe m4_refT(lock_vec) is used to acquire and release locks.  Them4_refT(lock_vec) performs any number of lock operations atomically.  Italso provides the capability to release all locks held by a particularlocker and release all the locks on a particular object.  (Performingmultiple lock operations atomically is useful in performing Btreetraversals -- you want to acquire a lock on a child page and onceacquired, immediately release the lock on its parent.  This istraditionally referred to as m4_italic(lock-coupling)).  Two additionalmethods, m4_ref(lock_get) and m4_ref(lock_put), are provided.  Thesemethods are simpler front-ends to the m4_ref(lock_vec) functionality,where m4_ref(lock_get) acquires a lock, and m4_ref(lock_put) releases alock that was acquired using m4_ref(lock_get) or m4_ref(lock_vec).  Alllocks explicitly requested by an application should be released viacalls to m4_ref(lock_put) or m4_ref(lock_vec).  Using m4_ref(lock_vec)instead of separate calls to m4_ref(lock_put) and m4_ref(lock_get) alsoreduces the synchronization overhead between multiple threads orprocesses.  The three methods are fully compatible, and may be usedinterchangeably.])m4_p([dnlApplications must specify lockers and lock objects appropriately.  Whenused with the m4_db access methods, lockers and objects are handledcompletely internally, but an application using the lock managerdirectly must either use the same conventions as the access methods ordefine its own convention to which it adheres.  If an application isusing the access methods with locking at the same time that it iscalling the lock manager directly, the application must follow aconvention that is compatible with the access methods' use of thelocking subsystem.  See m4_link(M4RELDIR/ref/lock/am_conv, [Accessmethod locking conventions]) for more information.])m4_p([dnlThe m4_ref(lock_id) function returns a unique ID that may safely be usedas the locker parameter to the m4_refT(lock_vec).  The access methodsuse m4_ref(lock_id) to generate unique lockers for the cursorsassociated with a database.])m4_p([dnlThe m4_ref(lock_detect) function provides the programmatic interface tothe m4_db deadlock detector.  Whenever two threads of control issue lockrequests concurrently, the possibility for deadlock arises.  A deadlockoccurs when two or more threads of control are blocked, waiting foractions that another one of the blocked threads must take.  For example,assume that threads A and B have each obtained read locks on object X.Now suppose that both threads want to obtain write locks on object X.Neither thread can be granted its write lock (because of the otherthread's read lock).  Both threads block and will never unblock becausethe event for which they are waiting can never happen.])m4_p([dnlThe deadlock detector examines all the locks held in the environment,and identifies situations where no thread can make forward progress.It then selects one of the participants in the deadlock (according tothe argument that was specified to m4_ref(dbenv_set_lk_detect)), andforces it to return the value m4_ref(DB_LOCK_DEADLOCK), which indicatesthat a deadlock occurred.  The thread receiving such an error mustrelease all of its locks and undo any incomplete modifications to thelocked resource.  Locks are typically released, and modificationsundone, by closing any cursors involved in the operation and abortingany transaction enclosing the operation.  The operation may optionallybe retried.])m4_p([dnlThe m4_ref(lock_stat) function returns information about the status ofthe lock subsystem.  It is the programmatic interface used by them4_ref(db_stat) utility.])m4_p([dnlThe locking subsystem is closed by the call to m4_ref(dbenv_close).])m4_p([dnlFinally, the entire locking subsystem may be discarded using them4_refT(dbenv_remove).])include(lock/m4.methods)m4_page_footer