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>Using advanced Berkeley DB features with dbstl</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="stl.html" title="Chapter��7.��Standard Template Library API" /> 11 <link rel="prev" href="stl_db_usage.html" title="Berkeley DB configuration" /> 12 <link rel="next" href="stl_txn_usage.html" title="Using transactions in dbstl" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Using advanced Berkeley DB features with dbstl</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="stl_db_usage.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��7.��Standard Template Library API</th> 23 <td width="20%" align="right">��<a accesskey="n" href="stl_txn_usage.html">Next</a></td> 24 </tr> 25 </table> 26 <hr /> 27 </div> 28 <div class="sect1" lang="en" xml:lang="en"> 29 <div class="titlepage"> 30 <div> 31 <div> 32 <h2 class="title" style="clear: both"><a id="stl_db_advanced_usage"></a>Using advanced Berkeley DB features with dbstl</h2> 33 </div> 34 </div> 35 </div> 36 <div class="toc"> 37 <dl> 38 <dt> 39 <span class="sect2"> 40 <a href="stl_db_advanced_usage.html#id1599057">Using bulk retrieval iterators</a> 41 </span> 42 </dt> 43 <dt> 44 <span class="sect2"> 45 <a href="stl_db_advanced_usage.html#id1599981">Using the DB_RMW flag</a> 46 </span> 47 </dt> 48 <dt> 49 <span class="sect2"> 50 <a href="stl_db_advanced_usage.html#id1599961">Using secondary index database and secondary containers</a> 51 </span> 52 </dt> 53 </dl> 54 </div> 55 <p> 56 This section describes advanced Berkeley DB features that are 57 available through dbstl. 58 </p> 59 <div class="sect2" lang="en" xml:lang="en"> 60 <div class="titlepage"> 61 <div> 62 <div> 63 <h3 class="title"><a id="id1599057"></a>Using bulk retrieval iterators</h3> 64 </div> 65 </div> 66 </div> 67 <p> 68 Bulk retrieval is an optimization option for const iterators and 69 nonconst but read-only iterators. Bulk retrieval can minimize the 70 number of database accesses performed by your application. It does this 71 by reading multiple entries at a time, which reduces read overhead. 72 Note that non-sequential reads will benefit less from, or even be hurt 73 by, this behavior, because it might result in unneeded data being read 74 from the database. Also, non-serializable reads may read obsolete 75 data, because part of the data read from the bulk read buffer may have 76 been updated since the retrieval. 77</p> 78 <p> 79 When using the default transaction isolation, iterators will perform 80 serializable reads. In this situation, the bulk-retrieved data cannot 81 be updated until the iterator's cursor is closed. 82</p> 83 <p> 84 Iterators using a different isolation levels, such as 85 <a href="../api_reference/C/dbcget.html#dbcget_DB_READ_COMMITTED" class="olink">DB_READ_COMMITTED</a> or <a href="../api_reference/C/dbopen.html#dbopen_DB_READ_UNCOMMITTED" class="olink">DB_READ_UNCOMMITTED</a> will not perform 86 serializable reads. The same is true for any iterators that do not use 87 transactions. 88</p> 89 <p> 90 A bulk retrieval iterator can only move in a singled direction, from 91 beginning to end. This means that iterators only support operator++, 92 and reverse iterators only support operator--. 93</p> 94 <p> 95 Iterator objects that use bulk retrieval might contain hundreds of 96 kilobytes of data, which makes copying the iterator object an expensive 97 operation. If possible, use ++iterator rather than iterator++. This 98 can save a useless copy construction of the iterator, as well as an 99 unnecessary dup/close of the cursor. 100</p> 101 <p> 102 You can configure bulk retrieval for each container using both in the 103 const and non-const version of the <code class="methodname">begin()</code> 104 method. The non-const version of <code class="methodname">begin()</code> will 105 return a read-only cursor. Note that read-only means something 106 different in C++ than it does when referring to an iterator. The latter 107 only means that it cannot be used to update the database. 108</p> 109 <p> 110 To configure the bulk retrieval buffer for an iterator when calling the 111 <code class="methodname">begin()</code> method, use the 112 <code class="function">BulkRetrievelItrOpt::bulk_retrieval(u_int32_t bulk_buffer_size)</code> 113 function. 114</p> 115 <p> 116 If you move a <code class="classname">db_vector_iterator</code> randomly rather 117 than sequentially, then dbstl will not perform bulk retrieval because 118 there is little performance gain from bulk retrieval in such an access 119 pattern. 120</p> 121 <p> 122 You can call <code class="function">iterator::set_bulk_buffer()</code> to modify 123 the iterator's bulk buffer size. Note that once bulk read is enabled, 124 only the bulk buffer size can be modified. This means that bulk read 125 cannot be disabled. Also, if bulk read was not enabled when you created 126 the iterator, you can't enable it after creation. 127</p> 128 <p> 129 Example code using this feature can be found in the 130 <code class="methodname">TestAssoc::test_bulk_retrieval_read()</code> method, 131 which is available in the the dbstl test suite. 132</p> 133 </div> 134 <div class="sect2" lang="en" xml:lang="en"> 135 <div class="titlepage"> 136 <div> 137 <div> 138 <h3 class="title"><a id="id1599981"></a>Using the DB_RMW flag</h3> 139 </div> 140 </div> 141 </div> 142 <p> 143 The <a href="../api_reference/C/dbcget.html#dbcget_DB_RMW" class="olink">DB_RMW</a> flag is an optimization for non-const (read-write) 144 iterators. This flag causes the underlying cursor to acquire a write 145 lock when reading so as to avoid deadlocks. Passing 146 <code class="function">ReadModifyWriteOption::read_modify_write()</code> to a 147 container's <code class="methodname">begin()</code> method creates an iterator 148 whose cursor has this behavior. 149</p> 150 </div> 151 <div class="sect2" lang="en" xml:lang="en"> 152 <div class="titlepage"> 153 <div> 154 <div> 155 <h3 class="title"><a id="id1599961"></a>Using secondary index database and secondary containers</h3> 156 </div> 157 </div> 158 </div> 159 <p> 160 Because duplicate keys are forbidden in primary databases, only 161 <code class="classname">db_map</code>, <code class="classname">db_set</code> and 162 <code class="classname">db_vector</code> are allowed to use primary databases. 163 For this reason, they are called 164 <span class="bold"><strong>primary containers</strong></span>. 165 A secondary database that supports duplicate keys can be used with 166 <code class="classname">db_multimap</code> containers. These are called 167 <span class="bold"><strong>secondary containers</strong></span>. Finally, a 168 secondary database that forbids duplicate keys can back a 169 <code class="classname">db_map</code> container. 170</p> 171 <p> 172 The <span class="bold"><strong>data_type</strong></span> of this 173 <code class="classname">db_multimap</code> secondary container is the 174 <span class="bold"><strong>data_type</strong></span> for the primary container. For 175 example, a <code class="classname">db_map<int, Person></code> object 176 where the <code class="classname">Person</code> class has an 177 <code class="literal">age</code> property of type <code class="literal">size_t</code>, a 178 <code class="classname">db_multimap<size_t, Person></code> using a 179 secondary database allows access to a person by age. 180</p> 181 <p> 182 183 A container created from a secondary database can only be used to 184 iterate, search or delete. It can not be used to update or insert. 185 While dbstl does expose the update and insert operations, Berkeley DB 186 does not, and an exception will be thrown if attempts are made to 187 insert objects into or update objects of a secondary container. 188</p> 189 <p> 190 Example code demonstrating this feature is available in 191 <code class="methodname">TestAssoc::test_secondary_containers()</code>, which 192 is available in the dbstl test suite. 193</p> 194 </div> 195 </div> 196 <div class="navfooter"> 197 <hr /> 198 <table width="100%" summary="Navigation footer"> 199 <tr> 200 <td width="40%" align="left"><a accesskey="p" href="stl_db_usage.html">Prev</a>��</td> 201 <td width="20%" align="center"> 202 <a accesskey="u" href="stl.html">Up</a> 203 </td> 204 <td width="40%" align="right">��<a accesskey="n" href="stl_txn_usage.html">Next</a></td> 205 </tr> 206 <tr> 207 <td width="40%" align="left" valign="top">Berkeley DB configuration��</td> 208 <td width="20%" align="center"> 209 <a accesskey="h" href="index.html">Home</a> 210 </td> 211 <td width="40%" align="right" valign="top">��Using transactions in dbstl</td> 212 </tr> 213 </table> 214 </div> 215 </body> 216</html> 217