1<!--$Id: intro.so,v 10.27 2006/11/13 18:05:02 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB Reference Guide: Introduction to the locking subsystem</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<a name="2"><!--meow--></a> 12<table width="100%"><tr valign=top> 13<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Locking Subsystem</dl></b></td> 14<td align=right><a href="../program/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../lock/config.html"><img src="../../images/next.gif" alt="Next"></a> 15</td></tr></table> 16<p align=center><b>Introduction to the locking subsystem</b></p> 17<p>The locking subsystem provides interprocess and intraprocess concurrency 18control mechanisms. Although the lock system is used extensively by 19the Berkeley DB access methods and transaction system, it may also be used as 20a standalone subsystem to provide concurrency control to any set of 21designated resources.</p> 22<p>The Lock subsystem is created, initialized, and opened by calls to 23<a href="../../api_c/env_open.html">DB_ENV->open</a> with the <a href="../../api_c/env_open.html#DB_INIT_LOCK">DB_INIT_LOCK</a> or <a href="../../api_c/env_open.html#DB_INIT_CDB">DB_INIT_CDB</a> 24flags specified.</p> 25<p>The <a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a> method is used to acquire and release locks. The 26<a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a> method performs any number of lock operations atomically. It 27also provides the capability to release all locks held by a particular 28locker and release all the locks on a particular object. (Performing 29multiple lock operations atomically is useful in performing Btree 30traversals -- you want to acquire a lock on a child page and once 31acquired, immediately release the lock on its parent. This is 32traditionally referred to as <i>lock-coupling</i>). Two additional 33methods, <a href="../../api_c/lock_get.html">DB_ENV->lock_get</a> and <a href="../../api_c/lock_put.html">DB_ENV->lock_put</a>, are provided. These 34methods are simpler front-ends to the <a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a> functionality, 35where <a href="../../api_c/lock_get.html">DB_ENV->lock_get</a> acquires a lock, and <a href="../../api_c/lock_put.html">DB_ENV->lock_put</a> releases a 36lock that was acquired using <a href="../../api_c/lock_get.html">DB_ENV->lock_get</a> or <a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a>. All 37locks explicitly requested by an application should be released via 38calls to <a href="../../api_c/lock_put.html">DB_ENV->lock_put</a> or <a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a>. Using <a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a> 39instead of separate calls to <a href="../../api_c/lock_put.html">DB_ENV->lock_put</a> and <a href="../../api_c/lock_get.html">DB_ENV->lock_get</a> also 40reduces the synchronization overhead between multiple threads or 41processes. The three methods are fully compatible, and may be used 42interchangeably.</p> 43<p>Applications must specify lockers and lock objects appropriately. When 44used with the Berkeley DB access methods, lockers and objects are handled 45completely internally, but an application using the lock manager 46directly must either use the same conventions as the access methods or 47define its own convention to which it adheres. If an application is 48using the access methods with locking at the same time that it is 49calling the lock manager directly, the application must follow a 50convention that is compatible with the access methods' use of the 51locking subsystem. See <a href="../../ref/lock/am_conv.html">Access 52method locking conventions</a> for more information.</p> 53<p>The <a href="../../api_c/lock_id.html">DB_ENV->lock_id</a> function returns a unique ID that may safely be used 54as the locker parameter to the <a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a> method. The access methods 55use <a href="../../api_c/lock_id.html">DB_ENV->lock_id</a> to generate unique lockers for the cursors 56associated with a database.</p> 57<p>The <a href="../../api_c/lock_detect.html">DB_ENV->lock_detect</a> function provides the programmatic interface to 58the Berkeley DB deadlock detector. Whenever two threads of control issue lock 59requests concurrently, the possibility for deadlock arises. A deadlock 60occurs when two or more threads of control are blocked, waiting for 61actions that another one of the blocked threads must take. For example, 62assume that threads A and B have each obtained read locks on object X. 63Now suppose that both threads want to obtain write locks on object X. 64Neither thread can be granted its write lock (because of the other 65thread's read lock). Both threads block and will never unblock because 66the event for which they are waiting can never happen.</p> 67<p>The deadlock detector examines all the locks held in the environment, 68and identifies situations where no thread can make forward progress. 69It then selects one of the participants in the deadlock (according to 70the argument that was specified to <a href="../../api_c/env_set_lk_detect.html">DB_ENV->set_lk_detect</a>), and 71forces it to return the value <a href="../../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a>, which indicates 72that a deadlock occurred. The thread receiving such an error must 73release all of its locks and undo any incomplete modifications to the 74locked resource. Locks are typically released, and modifications 75undone, by closing any cursors involved in the operation and aborting 76any transaction enclosing the operation. The operation may optionally 77be retried.</p> 78<p>The <a href="../../api_c/lock_stat.html">DB_ENV->lock_stat</a> function returns information about the status of 79the lock subsystem. It is the programmatic interface used by the 80<a href="../../utility/db_stat.html">db_stat</a> utility.</p> 81<p>The locking subsystem is closed by the call to <a href="../../api_c/env_close.html">DB_ENV->close</a>.</p> 82<p>Finally, the entire locking subsystem may be discarded using the 83<a href="../../api_c/env_remove.html">DB_ENV->remove</a> method.</p> 84<!--$Id: m4.methods,v 1.7 2008/01/28 23:59:30 sarette Exp $--> 85<table border=1 align=center> 86<tr><th>Locking Subsystem and Related Methods</th><th>Description</th></tr> 87<!--DbDeadlockException--> 88<!--DbEnv::lock_detect--><tr><td><a href="../../api_c/lock_detect.html">DB_ENV->lock_detect</a></td><td>Perform deadlock detection</td></tr> 89<!--DbEnv::lock_get--><tr><td><a href="../../api_c/lock_get.html">DB_ENV->lock_get</a></td><td>Acquire a lock</td></tr> 90<!--DbEnv::lock_id--><tr><td><a href="../../api_c/lock_id.html">DB_ENV->lock_id</a></td><td>Acquire a locker ID</td></tr> 91<!--DbEnv::lock_id_free--><tr><td><a href="../../api_c/lock_id_free.html">DB_ENV->lock_id_free</a></td><td>Release a locker ID</td></tr> 92<!--DbEnv::lock_put--><tr><td><a href="../../api_c/lock_put.html">DB_ENV->lock_put</a></td><td>Release a lock</td></tr> 93<!--DbEnv::lock_stat--><tr><td><a href="../../api_c/lock_stat.html">DB_ENV->lock_stat</a></td><td>Return lock subsystem statistics</td></tr> 94<!--DbEnv::lock_vec--><tr><td><a href="../../api_c/lock_vec.html">DB_ENV->lock_vec</a></td><td>Acquire/release locks</td></tr> 95<!--DbEnv::cdsgroup_begin--><tr><td><a href="../../api_c/env_cdsgroup_begin.html">DB_ENV->cdsgroup_begin</a></td><td>Get a locker ID in Berkeley DB Concurrent Data Store</td></tr> 96<!--DbLockNotGrantedException--> 97<!--DbLock--> 98<tr><th>Locking Subsystem Configuration</th><th><br></th></tr> 99<!--DbEnv::set_lk_conflicts--><tr><td><a href="../../api_c/env_set_lk_conflicts.html">DB_ENV->set_lk_conflicts</a></td><td>Set lock conflicts matrix</td></tr> 100<!--DbEnv::set_lk_max_detect--><tr><td><a href="../../api_c/env_set_lk_detect.html">DB_ENV->set_lk_detect</a></td><td>Set automatic deadlock detection</td></tr> 101<!--DbEnv::set_lk_max_lockers--><tr><td><a href="../../api_c/env_set_lk_max_lockers.html">DB_ENV->set_lk_max_lockers</a></td><td>Set maximum number of lockers</td></tr> 102<!--DbEnv::set_lk_max_locks--><tr><td><a href="../../api_c/env_set_lk_max_locks.html">DB_ENV->set_lk_max_locks</a></td><td>Set maximum number of locks</td></tr> 103<!--DbEnv::set_lk_max_objects--><tr><td><a href="../../api_c/env_set_lk_max_objects.html">DB_ENV->set_lk_max_objects</a></td><td>Set maximum number of lock objects</td></tr> 104<!--DbEnv::set_lk_partitions--><tr><td><a href="../../api_c/env_set_lk_partitions.html">DB_ENV->set_lk_partitions</a></td><td>Set number of lock partitions</td></tr> 105<!--DbEnv::set_timeout--><tr><td><a href="../../api_c/env_set_timeout.html">DB_ENV->set_timeout</a></td><td>Set lock and transaction timeout</td></tr> 106</table> 107<table width="100%"><tr><td><br></td><td align=right><a href="../program/faq.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../lock/config.html"><img src="../../images/next.gif" alt="Next"></a> 108</td></tr></table> 109<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 110</body> 111</html> 112
