mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-16 09:06:25 +00:00
217 lines
9.7 KiB
HTML
217 lines
9.7 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 11.2.5.3</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#idp1232296">Using bulk retrieval iterators</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="stl_db_advanced_usage.html#idp1232520">Using the DB_RMW flag</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="stl_db_advanced_usage.html#idp1199288">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="idp1232296"></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="idp1232520"></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="idp1199288"></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>
|