diff options
Diffstat (limited to 'docs/programmer_reference/lock.html')
| -rw-r--r-- | docs/programmer_reference/lock.html | 200 |
1 files changed, 119 insertions, 81 deletions
diff --git a/docs/programmer_reference/lock.html b/docs/programmer_reference/lock.html index a8e1b422..692326e6 100644 --- a/docs/programmer_reference/lock.html +++ b/docs/programmer_reference/lock.html @@ -14,13 +14,11 @@ <body> <div xmlns="" class="navheader"> <div class="libver"> - <p>Library Version 11.2.5.3</p> + <p>Library Version 12.1.6.1</p> </div> <table width="100%" summary="Navigation header"> <tr> - <th colspan="3" align="center">Chapter 16. - The Locking Subsystem - </th> + <th colspan="3" align="center">Chapter 16. The Locking Subsystem </th> </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="program_faq.html">Prev</a> </td> @@ -34,9 +32,7 @@ <div class="titlepage"> <div> <div> - <h2 class="title"><a id="lock"></a>Chapter 16. - The Locking Subsystem - </h2> + <h2 class="title"><a id="lock"></a>Chapter 16. The Locking Subsystem </h2> </div> </div> </div> @@ -47,7 +43,8 @@ <dl> <dt> <span class="sect1"> - <a href="lock.html#lock_intro">Introduction to the locking subsystem</a> + <a href="lock.html#lock_intro">Introduction to the locking + subsystem</a> </span> </dt> <dt> @@ -57,7 +54,8 @@ </dt> <dt> <span class="sect1"> - <a href="lock_max.html">Configuring locking: sizing the system</a> + <a href="lock_max.html">Configuring locking: sizing the + system</a> </span> </dt> <dt> @@ -72,7 +70,8 @@ </dt> <dt> <span class="sect1"> - <a href="lock_timeout.html">Deadlock detection using timers</a> + <a href="lock_timeout.html">Deadlock detection using + timers</a> </span> </dt> <dt> @@ -92,7 +91,8 @@ </dt> <dt> <span class="sect1"> - <a href="lock_twopl.html">Locking with transactions: two-phase locking</a> + <a href="lock_twopl.html">Locking with transactions: two-phase + locking</a> </span> </dt> <dt> @@ -102,12 +102,14 @@ </dt> <dt> <span class="sect1"> - <a href="lock_am_conv.html">Berkeley DB Transactional Data Store locking conventions</a> + <a href="lock_am_conv.html">Berkeley DB Transactional Data + Store locking conventions</a> </span> </dt> <dt> <span class="sect1"> - <a href="lock_nondb.html">Locking and non-Berkeley DB applications</a> + <a href="lock_nondb.html">Locking and non-Berkeley DB + applications</a> </span> </dt> </dl> @@ -116,77 +118,113 @@ <div class="titlepage"> <div> <div> - <h2 class="title" style="clear: both"><a id="lock_intro"></a>Introduction to the locking subsystem</h2> + <h2 class="title" style="clear: both"><a id="lock_intro"></a>Introduction to the locking + subsystem</h2> </div> </div> </div> - <p>The locking subsystem provides interprocess and intraprocess concurrency -control mechanisms. Although the lock system is used extensively by -the Berkeley DB access methods and transaction system, it may also be used as -a standalone subsystem to provide concurrency control to any set of -designated resources.</p> - <p>The Lock subsystem is created, initialized, and opened by calls to -<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> -flags specified.</p> - <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 -<a href="../api_reference/C/lockvec.html" class="olink">DB_ENV->lock_vec()</a> method performs any number of lock operations atomically. It -also provides the capability to release all locks held by a particular -locker and release all the locks on a particular object. (Performing -multiple lock operations atomically is useful in performing Btree -traversals -- you want to acquire a lock on a child page and once -acquired, immediately release the lock on its parent. This is -traditionally referred to as <span class="emphasis"><em>lock-coupling</em></span>). Two additional -methods, <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 -methods are simpler front-ends to the <a href="../api_reference/C/lockvec.html" class="olink">DB_ENV->lock_vec()</a> functionality, -where <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 -lock 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 -locks explicitly requested by an application should be released via -calls 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> -instead of separate calls to <a href="../api_reference/C/lockput.html" class="olink">DB_ENV->lock_put()</a> and <a href="../api_reference/C/lockget.html" class="olink">DB_ENV->lock_get()</a> also -reduces the synchronization overhead between multiple threads or -processes. The three methods are fully compatible, and may be used -interchangeably.</p> - <p>Applications must specify lockers and lock objects appropriately. When -used with the Berkeley DB access methods, lockers and objects are handled -completely internally, but an application using the lock manager -directly must either use the same conventions as the access methods or -define its own convention to which it adheres. If an application is -using the access methods with locking at the same time that it is -calling the lock manager directly, the application must follow a -convention that is compatible with the access methods' use of the -locking 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> - <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 -as the locker parameter to the <a href="../api_reference/C/lockvec.html" class="olink">DB_ENV->lock_vec()</a> method. The access methods -use <a href="../api_reference/C/lockid.html" class="olink">DB_ENV->lock_id()</a> to generate unique lockers for the cursors -associated with a database.</p> - <p>The <a href="../api_reference/C/lockdetect.html" class="olink">DB_ENV->lock_detect()</a> function provides the programmatic interface to -the Berkeley DB deadlock detector. Whenever two threads of control issue lock -requests concurrently, the possibility for deadlock arises. A deadlock -occurs when two or more threads of control are blocked, waiting for -actions 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 other -thread's read lock). Both threads block and will never unblock because -the event for which they are waiting can never happen.</p> - <p>The 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 to -the argument that was specified to <a href="../api_reference/C/envset_lk_detect.html" class="olink">DB_ENV->set_lk_detect()</a>), and -forces it to return the value <a class="link" href="program_errorret.html#program_errorret.DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a>, which indicates -that a deadlock occurred. The thread receiving such an error must -release all of its locks and undo any incomplete modifications to the -locked resource. Locks are typically released, and modifications -undone, by closing any cursors involved in the operation and aborting -any transaction enclosing the operation. The operation may optionally -be retried.</p> - <p>The <a href="../api_reference/C/lockstat.html" class="olink">DB_ENV->lock_stat()</a> function returns information about the status of -the lock subsystem. It is the programmatic interface used by the -<a href="../api_reference/C/db_stat.html" class="olink">db_stat</a> utility.</p> - <p>The locking subsystem is closed by the call to <a href="../api_reference/C/envclose.html" class="olink">DB_ENV->close()</a>.</p> - <p>Finally, the entire locking subsystem may be discarded using the -<a href="../api_reference/C/envremove.html" class="olink">DB_ENV->remove()</a> method.</p> - <p>For more information on the locking subsystem methods, see the <a href="../api_reference/C/lock.html#locklist" class="olink">Locking Subsystem and Related Methods</a> section in the <em class="citetitle">Berkeley DB C API Reference Guide.</em> </p> + <p> + The locking subsystem provides interprocess and intraprocess + concurrency control mechanisms. Although the lock system is + used extensively by the Berkeley DB access methods and + transaction system, it may also be used as a standalone + subsystem to provide concurrency control to any set of + designated resources. + </p> + <p> + The Lock subsystem is created, initialized, and opened by + calls to <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> + flags specified. + </p> + <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 <a href="../api_reference/C/lockvec.html" class="olink">DB_ENV->lock_vec()</a> method performs any number of lock operations + atomically. It also provides the capability to release all + locks held by a particular locker and release all the locks on + a particular object. (Performing multiple lock operations + atomically is useful in performing Btree traversals -- you + want to acquire a lock on a child page and once acquired, + immediately release the lock on its parent. This is + traditionally referred to as + <span class="emphasis"><em>lock-coupling</em></span>). Two additional + methods, <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 methods + are simpler front-ends to the <a href="../api_reference/C/lockvec.html" class="olink">DB_ENV->lock_vec()</a> functionality, where + <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 lock 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 locks + explicitly requested by an application should be released via + calls 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> instead of + separate calls to <a href="../api_reference/C/lockput.html" class="olink">DB_ENV->lock_put()</a> and <a href="../api_reference/C/lockget.html" class="olink">DB_ENV->lock_get()</a> also reduces the + synchronization overhead between multiple threads or + processes. The three methods are fully compatible, and may be + used interchangeably. + </p> + <p> + Applications must specify lockers and lock objects + appropriately. When used with the Berkeley DB access methods, + lockers and objects are handled completely internally, but an + application using the lock manager directly must either use + the same conventions as the access methods or define its own + convention to which it adheres. If an application is using the + access methods with locking at the same time that it is + calling the lock manager directly, the application must follow + a convention that is compatible with the access methods' use + of the locking 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> + <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 as the locker parameter to the <a href="../api_reference/C/lockvec.html" class="olink">DB_ENV->lock_vec()</a> method. The + access methods use <a href="../api_reference/C/lockid.html" class="olink">DB_ENV->lock_id()</a> to generate unique lockers for the + cursors associated with a database. + </p> + <p> + The <a href="../api_reference/C/lockdetect.html" class="olink">DB_ENV->lock_detect()</a> function provides the programmatic + interface to the Berkeley DB deadlock detector. Whenever two + threads of control issue lock requests concurrently, the + possibility for deadlock arises. A deadlock occurs when two or + more threads of control are blocked, waiting for actions 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 other thread's read lock). Both threads + block and will never unblock because the event for which they + are waiting can never happen. + </p> + <p> + The 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 to the argument that was specified + to <a href="../api_reference/C/envset_lk_detect.html" class="olink">DB_ENV->set_lk_detect()</a>), and forces it to return the value + <a class="link" href="program_errorret.html#program_errorret.DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a>, + which indicates that a deadlock occurred. The thread receiving such an + error must release all of its locks and undo any incomplete modifications to the + locked resource. Locks are typically released, and + modifications undone, by closing any cursors involved in the + operation and aborting any transaction enclosing the + operation. The operation may optionally be retried. + </p> + <p> + The <a href="../api_reference/C/lockstat.html" class="olink">DB_ENV->lock_stat()</a> function returns information about the status + of the lock subsystem. It is the programmatic interface used + by the <a href="../api_reference/C/db_stat.html" class="olink">db_stat</a> utility. + </p> + <p> + The locking subsystem is closed by the call to + <a href="../api_reference/C/envclose.html" class="olink">DB_ENV->close()</a>. + </p> + <p> + Finally, the entire locking subsystem may be discarded using + the <a href="../api_reference/C/envremove.html" class="olink">DB_ENV->remove()</a> method. + </p> + <p> + For more information on the locking subsystem methods, see + the <a href="../api_reference/C/lock.html#locklist" class="olink">Locking + Subsystem and Related Methods</a> section in the + <em class="citetitle">Berkeley DB C API Reference Guide.</em> + </p> </div> </div> <div class="navfooter"> |