1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>Chapter��15.�� The Locking Subsystem</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" /> 10 <link rel="up" href="index.html" title="Berkeley DB Programmer's Reference Guide" /> 11 <link rel="prev" href="program_faq.html" title="Programmer notes FAQ" /> 12 <link rel="next" href="lock_config.html" title="Configuring locking" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Chapter��15.�� 19 The Locking Subsystem 20 </th> 21 </tr> 22 <tr> 23 <td width="20%" align="left"><a accesskey="p" href="program_faq.html">Prev</a>��</td> 24 <th width="60%" align="center">��</th> 25 <td width="20%" align="right">��<a accesskey="n" href="lock_config.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="chapter" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title"><a id="lock"></a>Chapter��15.�� 35 The Locking Subsystem 36 </h2> 37 </div> 38 </div> 39 </div> 40 <div class="toc"> 41 <p> 42 <b>Table of Contents</b> 43 </p> 44 <dl> 45 <dt> 46 <span class="sect1"> 47 <a href="lock.html#lock_intro">Introduction to the locking subsystem</a> 48 </span> 49 </dt> 50 <dt> 51 <span class="sect1"> 52 <a href="lock_config.html">Configuring locking</a> 53 </span> 54 </dt> 55 <dt> 56 <span class="sect1"> 57 <a href="lock_max.html">Configuring locking: sizing the system</a> 58 </span> 59 </dt> 60 <dt> 61 <span class="sect1"> 62 <a href="lock_stdmode.html">Standard lock modes</a> 63 </span> 64 </dt> 65 <dt> 66 <span class="sect1"> 67 <a href="lock_dead.html">Deadlock detection</a> 68 </span> 69 </dt> 70 <dt> 71 <span class="sect1"> 72 <a href="lock_timeout.html">Deadlock detection using timers</a> 73 </span> 74 </dt> 75 <dt> 76 <span class="sect1"> 77 <a href="lock_deaddbg.html">Deadlock debugging</a> 78 </span> 79 </dt> 80 <dt> 81 <span class="sect1"> 82 <a href="lock_page.html">Locking granularity</a> 83 </span> 84 </dt> 85 <dt> 86 <span class="sect1"> 87 <a href="lock_notxn.html">Locking without transactions</a> 88 </span> 89 </dt> 90 <dt> 91 <span class="sect1"> 92 <a href="lock_twopl.html">Locking with transactions: two-phase locking</a> 93 </span> 94 </dt> 95 <dt> 96 <span class="sect1"> 97 <a href="lock_cam_conv.html">Berkeley DB Concurrent Data Store locking conventions</a> 98 </span> 99 </dt> 100 <dt> 101 <span class="sect1"> 102 <a href="lock_am_conv.html">Berkeley DB Transactional Data Store locking conventions</a> 103 </span> 104 </dt> 105 <dt> 106 <span class="sect1"> 107 <a href="lock_nondb.html">Locking and non-Berkeley DB applications</a> 108 </span> 109 </dt> 110 </dl> 111 </div> 112 <div class="sect1" lang="en" xml:lang="en"> 113 <div class="titlepage"> 114 <div> 115 <div> 116 <h2 class="title" style="clear: both"><a id="lock_intro"></a>Introduction to the locking subsystem</h2> 117 </div> 118 </div> 119 </div> 120 <p>The locking subsystem provides interprocess and intraprocess concurrency 121control mechanisms. Although the lock system is used extensively by 122the Berkeley DB access methods and transaction system, it may also be used as 123a standalone subsystem to provide concurrency control to any set of 124designated resources.</p> 125 <p>The Lock subsystem is created, initialized, and opened by calls to 126<a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> with the <a href="../api_reference/C/envopen.html#envopen_DB_INIT_LOCK" class="olink">DB_INIT_LOCK</a> or <a href="../api_reference/C/envopen.html#envopen_DB_INIT_CDB" class="olink">DB_INIT_CDB</a> 127flags specified.</p> 128 <p>The <a href="../api_reference/C/lockvec.html" class="olink">DB_ENV->lock_vec()</a> method is used to acquire and release locks. The 129<a href="../api_reference/C/lockvec.html" class="olink">DB_ENV->lock_vec()</a> method performs any number of lock operations atomically. It 130also provides the capability to release all locks held by a particular 131locker and release all the locks on a particular object. (Performing 132multiple lock operations atomically is useful in performing Btree 133traversals -- you want to acquire a lock on a child page and once 134acquired, immediately release the lock on its parent. This is 135traditionally referred to as <span class="emphasis"><em>lock-coupling</em></span>). Two additional 136methods, <a href="../api_reference/C/lockget.html" class="olink">DB_ENV->lock_get()</a> and <a href="../api_reference/C/lockput.html" class="olink">DB_ENV->lock_put()</a>, are provided. These 137methods are simpler front-ends to the <a href="../api_reference/C/lockvec.html" class="olink">DB_ENV->lock_vec()</a> functionality, 138where <a href="../api_reference/C/lockget.html" class="olink">DB_ENV->lock_get()</a> acquires a lock, and <a href="../api_reference/C/lockput.html" class="olink">DB_ENV->lock_put()</a> releases a 139lock that was acquired using <a href="../api_reference/C/lockget.html" class="olink">DB_ENV->lock_get()</a> or <a href="../api_reference/C/lockvec.html" class="olink">DB_ENV->lock_vec()</a>. All 140locks explicitly requested by an application should be released via 141calls to <a href="../api_reference/C/lockput.html" class="olink">DB_ENV->lock_put()</a> or <a href="../api_reference/C/lockvec.html" class="olink">DB_ENV->lock_vec()</a>. Using <a href="../api_reference/C/lockvec.html" class="olink">DB_ENV->lock_vec()</a> 142instead of separate calls to <a href="../api_reference/C/lockput.html" class="olink">DB_ENV->lock_put()</a> and <a href="../api_reference/C/lockput.html" class="olink">DB_ENV->lock_put()</a> also 143reduces the synchronization overhead between multiple threads or 144processes. The three methods are fully compatible, and may be used 145interchangeably.</p> 146 <p>Applications must specify lockers and lock objects appropriately. When 147used with the Berkeley DB access methods, lockers and objects are handled 148completely internally, but an application using the lock manager 149directly must either use the same conventions as the access methods or 150define its own convention to which it adheres. If an application is 151using the access methods with locking at the same time that it is 152calling the lock manager directly, the application must follow a 153convention that is compatible with the access methods' use of the 154locking subsystem. See <a class="xref" href="lock_am_conv.html" title="Berkeley DB Transactional Data Store locking conventions">Berkeley DB Transactional Data Store locking conventions</a> for more information.</p> 155 <p>The <a href="../api_reference/C/lockid.html" class="olink">DB_ENV->lock_id()</a> function returns a unique ID that may safely be used 156as the locker parameter to the <a href="../api_reference/C/lockvec.html" class="olink">DB_ENV->lock_vec()</a> method. The access methods 157use <a href="../api_reference/C/lockid.html" class="olink">DB_ENV->lock_id()</a> to generate unique lockers for the cursors 158associated with a database.</p> 159 <p>The <a href="../api_reference/C/lockdetect.html" class="olink">DB_ENV->lock_detect()</a> function provides the programmatic interface to 160the Berkeley DB deadlock detector. Whenever two threads of control issue lock 161requests concurrently, the possibility for deadlock arises. A deadlock 162occurs when two or more threads of control are blocked, waiting for 163actions that another one of the blocked threads must take. For example, 164assume that threads A and B have each obtained read locks on object X. 165Now suppose that both threads want to obtain write locks on object X. 166Neither thread can be granted its write lock (because of the other 167thread's read lock). Both threads block and will never unblock because 168the event for which they are waiting can never happen.</p> 169 <p>The deadlock detector examines all the locks held in the environment, 170and identifies situations where no thread can make forward progress. 171It then selects one of the participants in the deadlock (according to 172the argument that was specified to <a href="../api_reference/C/envset_lk_detect.html" class="olink">DB_ENV->set_lk_detect()</a>), and 173forces it to return the value <a class="link" href="program_errorret.html#program_errorret.DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a>, which indicates 174that a deadlock occurred. The thread receiving such an error must 175release all of its locks and undo any incomplete modifications to the 176locked resource. Locks are typically released, and modifications 177undone, by closing any cursors involved in the operation and aborting 178any transaction enclosing the operation. The operation may optionally 179be retried.</p> 180 <p>The <a href="../api_reference/C/lockstat.html" class="olink">DB_ENV->lock_stat()</a> function returns information about the status of 181the lock subsystem. It is the programmatic interface used by the 182<a href="../api_reference/C/db_stat.html" class="olink">db_stat utility</a>.</p> 183 <p>The locking subsystem is closed by the call to <a href="../api_reference/C/envclose.html" class="olink">DB_ENV->close()</a>.</p> 184 <p>Finally, the entire locking subsystem may be discarded using the 185<a href="../api_reference/C/envremove.html" class="olink">DB_ENV->remove()</a> method.</p> 186 <div class="informaltable"> 187 <table border="1" width="80%"> 188 <colgroup> 189 <col /> 190 <col /> 191 </colgroup> 192 <thead> 193 <tr> 194 <th>Locking Subsystem and Related Methods</th> 195 <th>Description</th> 196 </tr> 197 </thead> 198 <tbody> 199 <tr> 200 <td> 201 <a href="../api_reference/C/lockdetect.html" class="olink">DB_ENV->lock_detect()</a> 202 </td> 203 <td>Perform deadlock detection</td> 204 </tr> 205 <tr> 206 <td> 207 <a href="../api_reference/C/lockget.html" class="olink">DB_ENV->lock_get()</a> 208 </td> 209 <td>Acquire a lock</td> 210 </tr> 211 <tr> 212 <td> 213 <a href="../api_reference/C/lockid.html" class="olink">DB_ENV->lock_id()</a> 214 </td> 215 <td>Acquire a locker ID</td> 216 </tr> 217 <tr> 218 <td> 219 <a href="../api_reference/C/lockid_free.html" class="olink">DB_ENV->lock_id_free()</a> 220 </td> 221 <td>Release a locker ID</td> 222 </tr> 223 <tr> 224 <td> 225 <a href="../api_reference/C/lockput.html" class="olink">DB_ENV->lock_put()</a> 226 </td> 227 <td>Release a lock</td> 228 </tr> 229 <tr> 230 <td> 231 <a href="../api_reference/C/lockstat.html" class="olink">DB_ENV->lock_stat()</a> 232 </td> 233 <td>Return lock subsystem statistics</td> 234 </tr> 235 <tr> 236 <td> 237 <a href="../api_reference/C/lockvec.html" class="olink">DB_ENV->lock_vec()</a> 238 </td> 239 <td>Acquire/release locks</td> 240 </tr> 241 <tr> 242 <td> 243 <a href="../api_reference/C/envcdsgroup_begin.html" class="olink">DB_ENV->cdsgroup_begin()</a> 244 </td> 245 <td>Get a locker ID in Berkeley DB Concurrent Data Store</td> 246 </tr> 247 <tr> 248 <td> 249 <span class="emphasis"> 250 <em>Locking Subsystem Configuration</em> 251 </span> 252 </td> 253 <td>��</td> 254 </tr> 255 <tr> 256 <td> 257 <a href="../api_reference/C/envset_lk_conflicts.html" class="olink">DB_ENV->set_lk_conflicts()</a> 258 </td> 259 <td>Set lock conflicts matrix</td> 260 </tr> 261 <tr> 262 <td> 263 <a href="../api_reference/C/envset_lk_detect.html" class="olink">DB_ENV->set_lk_detect()</a> 264 </td> 265 <td>Set automatic deadlock detection</td> 266 </tr> 267 <tr> 268 <td> 269 <a href="../api_reference/C/envset_lk_max_lockers.html" class="olink">DB_ENV->set_lk_max_lockers()</a> 270 </td> 271 <td>Set maximum number of lockers</td> 272 </tr> 273 <tr> 274 <td> 275 <a href="../api_reference/C/envset_lk_max_locks.html" class="olink">DB_ENV->set_lk_max_locks()</a> 276 </td> 277 <td>Set maximum number of locks</td> 278 </tr> 279 <tr> 280 <td> 281 <a href="../api_reference/C/envset_lk_max_objects.html" class="olink">DB_ENV->set_lk_max_objects()</a> 282 </td> 283 <td>Set maximum number of lock objects</td> 284 </tr> 285 <tr> 286 <td> 287 <a href="../api_reference/C/envset_lk_partitions.html" class="olink">DB_ENV->set_lk_partitions()</a> 288 </td> 289 <td>Set number of lock partitions</td> 290 </tr> 291 <tr> 292 <td> 293 <a href="../api_reference/C/envset_timeout.html" class="olink">DB_ENV->set_timeout()</a> 294 </td> 295 <td>Set lock and transaction timeout</td> 296 </tr> 297 </tbody> 298 </table> 299 </div> 300 </div> 301 </div> 302 <div class="navfooter"> 303 <hr /> 304 <table width="100%" summary="Navigation footer"> 305 <tr> 306 <td width="40%" align="left"><a accesskey="p" href="program_faq.html">Prev</a>��</td> 307 <td width="20%" align="center">��</td> 308 <td width="40%" align="right">��<a accesskey="n" href="lock_config.html">Next</a></td> 309 </tr> 310 <tr> 311 <td width="40%" align="left" valign="top">Programmer notes FAQ��</td> 312 <td width="20%" align="center"> 313 <a accesskey="h" href="index.html">Home</a> 314 </td> 315 <td width="40%" align="right" valign="top">��Configuring locking</td> 316 </tr> 317 </table> 318 </div> 319 </body> 320</html> 321