mirror of
https://github.com/yasuhirokimura/db18
synced 2026-06-08 18:29:23 +00:00
Yasuhiro KIMURA
239 lines
11 KiB
HTML
239 lines
11 KiB
HTML
<?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 18.1.40</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#idm140654539553920">Using bulk retrieval iterators</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="stl_db_advanced_usage.html#idm140654539549136">Using the DB_RMW flag</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="stl_db_advanced_usage.html#idm140654539451488">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="idm140654539553920"></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="idm140654539549136"></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="idm140654539451488"></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>
|