docs/gsg_txn/CXX/txn_ccursor.html

   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>Transactional Cursors and Concurrent 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="Getting Started with Berkeley DB Transaction Processing" />
  10     <link rel="up" href="txnconcurrency.html" title="Chapter 4. Concurrency" />
  11     <link rel="prev" href="isolation.html" title="Isolation" />
  12     <link rel="next" href="exclusivelock.html" title="Exclusive Database Handles" />
  13   </head>
  14   <body>
  15     <div xmlns="" class="navheader">
  16       <div class="libver">
  17         <p>Library Version 11.2.5.3</p>
  18       </div>
  19       <table width="100%" summary="Navigation header">
  20         <tr>
  21           <th colspan="3" align="center">Transactional Cursors and Concurrent Applications</th>
  22         </tr>
  23         <tr>
  24           <td width="20%" align="left"><a accesskey="p" href="isolation.html">Prev</a> </td>
  25           <th width="60%" align="center">Chapter 4. Concurrency</th>
  26           <td width="20%" align="right"> <a accesskey="n" href="exclusivelock.html">Next</a></td>
  27         </tr>
  28       </table>
  29       <hr />
  30     </div>
  31     <div class="sect1" lang="en" xml:lang="en">
  32       <div class="titlepage">
  33         <div>
  34           <div>
  35             <h2 class="title" style="clear: both"><a id="txn_ccursor"></a>Transactional Cursors and Concurrent Applications</h2>
  36           </div>
  37         </div>
  38       </div>
  39       <div class="toc">
  40         <dl>
  41           <dt>
  42             <span class="sect2">
  43               <a href="txn_ccursor.html#cursordirtyreads">Using Cursors with Uncommitted Data</a>
  44             </span>
  45           </dt>
  46         </dl>
  47       </div>
  48       <p>
  49             When you use transactional cursors with a concurrent application, remember that
  50             in the event of a deadlock you must make sure that you close your cursor before you abort and retry your
  51             transaction.
  52          </p>
  53       <p>
  54             Also, remember that when you are using the default isolation level,
  55             every time your cursor reads a record it locks
  56             that record until the encompassing transaction is resolved. This
  57             means that walking your database with a transactional cursor
  58             increases the chance of lock contention.
  59           </p>
  60       <p>
  61                 For this reason, if you must routinely walk your database with a
  62                 transactional cursor, consider using a reduced isolation level
  63                 such as read committed.
  64           </p>
  65       <div class="sect2" lang="en" xml:lang="en">
  66         <div class="titlepage">
  67           <div>
  68             <div>
  69               <h3 class="title"><a id="cursordirtyreads"></a>Using Cursors with Uncommitted Data</h3>
  70             </div>
  71           </div>
  72         </div>
  73         <p>
  74
  75                 As described in <a class="xref" href="isolation.html#dirtyreads" title="Reading Uncommitted Data">Reading Uncommitted Data</a>
  76                 above, it is possible to relax your transaction's isolation
  77                 level such that it can read data modified but not yet committed
  78                 by another transaction. You can configure this when you create
  79                 your transaction handle, and when you do so then all cursors opened
  80                 inside that transaction will automatically use uncommitted reads.
  81             </p>
  82         <p>
  83                 You can also do this when you create a cursor handle from within
  84                 a serializable transaction.  When you do this, only those
  85                 cursors configured for uncommitted reads uses uncommitted reads.
  86             </p>
  87         <p>
  88                     Either way, you must first configure your database
  89                      handle to support
  90                 uncommitted reads before you can configure your transactions or
  91                 your cursors to use them.
  92             </p>
  93         <p>
  94                 The following example shows how to configure an individual cursor handle
  95                 to read uncommitted data from within a serializable (full isolation) transaction.
  96                 For an example of
  97                 configuring a transaction to perform uncommitted reads in
  98                 general, see <a class="xref" href="isolation.html#dirtyreads" title="Reading Uncommitted Data">Reading Uncommitted Data</a>.
  99             </p>
 100         <pre class="programlisting">#include "db_cxx.h"
 101
 102 ...
 103
 104 int main(void)
 105 {
 106     u_int32_t env_flags = DB_CREATE     |  // If the environment does not
 107                                            // exist, create it.
 108                           DB_INIT_LOCK  |  // Initialize locking
 109                           DB_INIT_LOG   |  // Initialize logging
 110                           DB_INIT_MPOOL |  // Initialize the cache
 111                           DB_INIT_TXN;     // Initialize transactions
 112
 113     u_int32_t db_flags = DB_CREATE |           // Create the db if it does
 114                                                // not exist
 115                          DB_AUTO_COMMIT |      // Enable auto commit
 116                          DB_READ_UNCOMMITTED;  // Enable uncommitted reads
 117
 118     Db *dbp = NULL;
 119     const char *file_name = "mydb.db";
 120
 121     std::string envHome("/export1/testEnv");
 122     DbEnv myEnv(0);
 123
 124     Dbc *cursorp = NULL;
 125
 126     try {
 127
 128         myEnv.open(envHome.c_str(), env_flags, 0);
 129         dbp = new Db(&amp;myEnv, 0);
 130         dbp-&gt;open(NULL,       // Txn pointer
 131                   file_name,  // File name
 132                   NULL,       // Logical db name
 133                   DB_BTREE,   // Database type (using btree)
 134                   db_flags,   // Open flags
 135                   0);         // File mode. Using defaults
 136
 137         DbTxn *txn = NULL;
 138         myEnv.txn_begin(NULL, &amp;txn, 0);
 139         try {
 140             // Get our cursor. Note that we pass the transaction
 141             // handle here. Note also that we pass the
 142             // DB_READ_UNCOMMITTED flag here so as to cause the
 143             // cursor to perform uncommitted reads.
 144             db.cursor(txn, &amp;cursorp, DB_READ_UNCOMMITTED);
 145
 146             // From here, you perform your cursor reads and writes
 147             // as normal, committing and aborting the transactions as
 148             // is necessary, and testing for deadlock exceptions as
 149             // normal (omitted for brevity).
 150
 151             ... </pre>
 152       </div>
 153     </div>
 154     <div class="navfooter">
 155       <hr />
 156       <table width="100%" summary="Navigation footer">
 157         <tr>
 158           <td width="40%" align="left"><a accesskey="p" href="isolation.html">Prev</a> </td>
 159           <td width="20%" align="center">
 160             <a accesskey="u" href="txnconcurrency.html">Up</a>
 161           </td>
 162           <td width="40%" align="right"> <a accesskey="n" href="exclusivelock.html">Next</a></td>
 163         </tr>
 164         <tr>
 165           <td width="40%" align="left" valign="top">Isolation </td>
 166           <td width="20%" align="center">
 167             <a accesskey="h" href="index.html">Home</a>
 168           </td>
 169           <td width="40%" align="right" valign="top"> Exclusive Database Handles</td>
 170         </tr>
 171       </table>
 172     </div>
 173   </body>
 174 </html>