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��10.�� Berkeley DB Concurrent Data Store Applications</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="env_faq.html" title="Environment FAQ" /> 12 <link rel="next" href="cam_fail.html" title="Handling failure in Data Store and Concurrent Data Store applications" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Chapter��10.�� 19 Berkeley DB Concurrent Data Store Applications 20 </th> 21 </tr> 22 <tr> 23 <td width="20%" align="left"><a accesskey="p" href="env_faq.html">Prev</a>��</td> 24 <th width="60%" align="center">��</th> 25 <td width="20%" align="right">��<a accesskey="n" href="cam_fail.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="cam"></a>Chapter��10.�� 35 Berkeley DB Concurrent Data Store Applications 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="cam.html#cam_intro">Concurrent Data Store introduction</a> 48 </span> 49 </dt> 50 <dt> 51 <span class="sect1"> 52 <a href="cam_fail.html">Handling failure in Data Store and Concurrent Data Store applications</a> 53 </span> 54 </dt> 55 <dt> 56 <span class="sect1"> 57 <a href="cam_app.html">Architecting Data Store and Concurrent Data Store applications</a> 58 </span> 59 </dt> 60 </dl> 61 </div> 62 <div class="sect1" lang="en" xml:lang="en"> 63 <div class="titlepage"> 64 <div> 65 <div> 66 <h2 class="title" style="clear: both"><a id="cam_intro"></a>Concurrent Data Store introduction</h2> 67 </div> 68 </div> 69 </div> 70 <p>It is often desirable to have concurrent read-write access to a database 71when there is no need for full recoverability or transaction semantics. 72For this class of applications, Berkeley DB provides interfaces supporting 73deadlock-free, multiple-reader/single writer access to the database. 74This means that at any instant in time, there may be either multiple 75readers accessing data or a single writer modifying data. The 76application is entirely unaware of which is happening, and Berkeley DB 77implements the necessary locking and blocking to ensure this behavior.</p> 78 <p>To create Berkeley DB Concurrent Data Store applications, you must first initialize an environment 79by calling <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a>. You must specify the <a href="../api_reference/C/envopen.html#envopen_DB_INIT_CDB" class="olink">DB_INIT_CDB</a> and <a href="../api_reference/C/envopen.html#envopen_DB_INIT_MPOOL" class="olink">DB_INIT_MPOOL</a> flags 80flags to that method. It is an error to 81specify any of the other <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> subsystem or recovery 82configuration flags, for example, <a href="../api_reference/C/envopen.html#envopen_DB_INIT_LOCK" class="olink">DB_INIT_LOCK</a>, <a href="../api_reference/C/envopen.html#envopen_DB_INIT_TXN" class="olink">DB_INIT_TXN</a> or <a href="../api_reference/C/envopen.html#envopen_DB_RECOVER" class="olink">DB_RECOVER</a> 83All databases must, of 84course, be created in this environment by using the <a href="../api_reference/C/dbcreate.html" class="olink">db_create()</a> 85function or <a href="../api_reference/CXX/db.html" class="olink">Db</a> constructor, and specifying the environment 86as an argument.</p> 87 <p>Berkeley DB performs appropriate locking so that safe enforcement of the 88deadlock-free, multiple-reader/single-writer semantic is transparent to 89the application. However, a basic understanding of Berkeley DB Concurrent Data Store locking 90behavior is helpful when writing Berkeley DB Concurrent Data Store applications.</p> 91 <p>Berkeley DB Concurrent Data Store 92avoids deadlocks without the need for a deadlock detector by performing 93all locking on an entire database at once (or on an entire environment 94in the case of the <a href="../api_reference/C/envset_flags.html#set_flags_DB_CDB_ALLDB" class="olink">DB_CDB_ALLDB</a> flag), and by ensuring that at 95any given time only one thread of control is allowed to simultaneously 96hold a read (shared) lock and attempt to acquire a write (exclusive) 97lock.</p> 98 <p>All open Berkeley DB cursors hold a read lock, which serves as a guarantee 99that the database will not change beneath them; likewise, all 100non-cursor <a href="../api_reference/C/dbget.html" class="olink">DB->get()</a> operations temporarily acquire and release 101a read lock that is held during the actual traversal of the database. 102Because read locks will not conflict with each other, any number of 103cursors in any number of threads of control may be open simultaneously, 104and any number of <a href="../api_reference/C/dbget.html" class="olink">DB->get()</a> operations may be concurrently in 105progress.</p> 106 <p>To enforce the rule that only one thread of control at a time can 107attempt to upgrade a read lock to a write lock, however, Berkeley DB must 108forbid multiple cursors from attempting to write concurrently. This is 109done using the <a href="../api_reference/C/dbcursor.html#cursor_DB_WRITECURSOR" class="olink">DB_WRITECURSOR</a> flag to the <a href="../api_reference/C/dbcursor.html" class="olink">DB->cursor()</a> method. 110This is the only difference between access method calls in Berkeley DB Concurrent Data Store and 111in the other Berkeley DB products. The <a href="../api_reference/C/dbcursor.html#cursor_DB_WRITECURSOR" class="olink">DB_WRITECURSOR</a> flag causes the 112newly created cursor to be a "write" cursor; that is, a cursor capable 113of performing writes as well as reads. Only cursors thus created are 114permitted to perform write operations (either deletes or puts), and only 115one such cursor can exist at any given time.</p> 116 <p>Any attempt to create a second write cursor or to perform a non-cursor 117write operation while a write cursor is open will block until that write 118cursor is closed. Read cursors may open and perform reads without blocking 119while a write cursor is extant. However, any attempts to actually perform 120a write, either using the write cursor or directly using the 121<a href="../api_reference/C/dbput.html" class="olink">DB->put()</a> or <a href="../api_reference/C/dbdel.html" class="olink">DB->del()</a> methods, will block until all read cursors 122are closed. This is how the multiple-reader/single-writer semantic is 123enforced, and prevents reads from seeing an inconsistent database state 124that may be an intermediate stage of a write operation.</p> 125 <p>By default, Berkeley DB Concurrent Data Store does locking on a per-database basis. For this 126reason, using cursors to access multiple databases in different orders 127in different threads or processes, or leaving cursors open on one 128database while accessing another database, can cause an application to 129hang. If this behavior is a requirement for the application, Berkeley DB 130should be configured to do locking on an environment-wide basis. See 131the <a href="../api_reference/C/envset_flags.html#set_flags_DB_CDB_ALLDB" class="olink">DB_CDB_ALLDB</a> flag of the <a href="../api_reference/C/envset_flags.html" class="olink">DB_ENV->set_flags()</a> method 132for more information.</p> 133 <p>With these behaviors, Berkeley DB can guarantee deadlock-free concurrent 134database access, so that multiple threads of control are free to perform 135reads and writes without needing to handle synchronization themselves 136or having to run a deadlock detector. Berkeley DB has no direct knowledge of 137which cursors belong to which threads, so some care must be taken to 138ensure that applications do not inadvertently block themselves, causing 139the application to hang and be unable to proceed.</p> 140 <p>As a consequence of the Berkeley DB Concurrent Data Store locking model, the following sequences 141of operations will cause a thread to block itself indefinitely:</p> 142 <div class="orderedlist"> 143 <ol type="1"> 144 <li>Keeping a cursor open while issuing a <a href="../api_reference/C/dbput.html" class="olink">DB->put()</a> or <a href="../api_reference/C/dbdel.html" class="olink">DB->del()</a> 145access method call.</li> 146 <li>Attempting to open a write cursor while another cursor is already being 147held open by the same thread of control. Note that it is correct 148operation for one thread of control to attempt to open a write cursor 149or to perform a non-cursor write (<a href="../api_reference/C/dbput.html" class="olink">DB->put()</a> or <a href="../api_reference/C/dbdel.html" class="olink">DB->del()</a>) 150while a write cursor is already active in another thread. It is only a 151problem if these things are done within a single thread of control -- 152in which case that thread will block and never be able to release the 153lock that is blocking it.</li> 154 <li>Not testing Berkeley DB error return codes (if any cursor operation returns 155an unexpected error, that cursor must still be closed).</li> 156 </ol> 157 </div> 158 <p>If the application needs to open multiple cursors in a single thread to 159perform an operation, it can indicate to Berkeley DB that the cursor locks 160should not block each other by creating a Berkeley DB Concurrent Data Store <span class="bold"><strong>group</strong></span>, using 161<a href="../api_reference/C/envcdsgroup_begin.html" class="olink">DB_ENV->cdsgroup_begin()</a>. This creates a locker ID that is shared by all 162cursors opened in the group.</p> 163 <p>Berkeley DB Concurrent Data Store groups use a <a href="../api_reference/C/txn.html" class="olink">TXN</a> handle to indicate the shared locker 164ID to Berkeley DB calls, and call <a href="../api_reference/C/txncommit.html" class="olink">DB_TXN->commit()</a> to end the group. This 165is a convenient way to pass the locked ID to the calls where it is 166needed, but should not be confused with the real transactional semantics 167provided by Berkeley DB Transactional Data Store. In particular, Berkeley DB Concurrent Data Store groups do not provide any 168abort or recovery facilities, and have no impact on durability of 169operations.</p> 170 </div> 171 </div> 172 <div class="navfooter"> 173 <hr /> 174 <table width="100%" summary="Navigation footer"> 175 <tr> 176 <td width="40%" align="left"><a accesskey="p" href="env_faq.html">Prev</a>��</td> 177 <td width="20%" align="center">��</td> 178 <td width="40%" align="right">��<a accesskey="n" href="cam_fail.html">Next</a></td> 179 </tr> 180 <tr> 181 <td width="40%" align="left" valign="top">Environment FAQ��</td> 182 <td width="20%" align="center"> 183 <a accesskey="h" href="index.html">Home</a> 184 </td> 185 <td width="40%" align="right" valign="top">��Handling failure in Data Store and Concurrent Data Store applications</td> 186 </tr> 187 </table> 188 </div> 189 </body> 190</html> 191