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