mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-16 17:16:25 +00:00
319 lines
13 KiB
HTML
319 lines
13 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>Berkeley DB configuration</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_examples.html" title="Dbstl examples" />
|
||
<link rel="next" href="stl_db_advanced_usage.html" title="Using advanced Berkeley DB features with dbstl" />
|
||
</head>
|
||
<body>
|
||
<div xmlns="" class="navheader">
|
||
<div class="libver">
|
||
<p>Library Version 11.2.5.2</p>
|
||
</div>
|
||
<table width="100%" summary="Navigation header">
|
||
<tr>
|
||
<th colspan="3" align="center">Berkeley DB configuration</th>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" align="left"><a accesskey="p" href="stl_examples.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_db_advanced_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_usage"></a>Berkeley DB configuration</h2>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="toc">
|
||
<dl>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="stl_db_usage.html#id3890274">Registering database and environment handles</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="stl_db_usage.html#id3890695">Truncate requirements</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="stl_db_usage.html#id3890858">Auto commit support</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="stl_db_usage.html#id3890555">Database and environment identity checks</a>
|
||
</span>
|
||
</dt>
|
||
<dt>
|
||
<span class="sect2">
|
||
<a href="stl_db_usage.html#id3890921">Products, constructors and configurations</a>
|
||
</span>
|
||
</dt>
|
||
</dl>
|
||
</div>
|
||
<p>
|
||
While dbstl behaves like the C++ STL APIs in most situations, there
|
||
are some Berkeley DB configuration activities that you can and
|
||
should perform using dbstl. These activities are described in the
|
||
following sections.
|
||
</p>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="id3890274"></a>Registering database and environment handles</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
Remember the following things as you use Berkeley DB Database
|
||
and Environment handles with dbstl:
|
||
</p>
|
||
<div class="itemizedlist">
|
||
<ul type="disc">
|
||
<li>
|
||
<p>
|
||
If you share environment or database handles among multiple
|
||
threads, remember to specify the <a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> flag in the open call to
|
||
the handle.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
If you create or open environment and/or database handles without
|
||
using the dbstl helper functions,
|
||
<code class="function">dbstl::open_db()</code> or
|
||
<code class="function">dbstl::open_env()</code>, remember that your
|
||
environment and database handles should be:
|
||
</p>
|
||
<div class="orderedlist">
|
||
<ol type="1">
|
||
<li>
|
||
<p>
|
||
Allocated in the heap via "new" operator.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
Created using the <a href="../api_reference/CXX/envcreate.html#env_DB_CXX_NO_EXCEPTIONS" class="olink">DB_CXX_NO_EXCEPTIONS</a> flag.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
In each thread sharing the handles, the handles are registered using
|
||
either <code class="function">dbstl::register_db()</code> or
|
||
<code class="function">dbstl::register_dbenv()</code>.
|
||
</p>
|
||
</li>
|
||
</ol>
|
||
</div>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
If you opened the database or environment handle using the
|
||
<code class="function">open_db()</code> or <code class="function">open_env()</code>
|
||
functions, the thread opening the handles should not call
|
||
<code class="function">register_db()</code> or <code class="function">register_env()</code>
|
||
again. This is because they have already been registered by the
|
||
<code class="function">open_db()</code> or <code class="function">open_env()</code>
|
||
functions. However, other threads sharing these handles still must register
|
||
them locally.
|
||
</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="id3890695"></a>Truncate requirements</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
Some Berkeley DB operations require there to be no open cursors on the
|
||
database handle at the time the operation occurs. Dbstl is aware of
|
||
these requirements, and will attempt to close the cursors opened in the
|
||
current thread when it performs these operations. However, the scope of
|
||
dbstl's activities in this regard are limited to the current thread; it
|
||
makes no attempt to close cursors opened in other threads. So you
|
||
are required to ensure there are no open cursors on database handles
|
||
shared across threads when operations are performed that require all
|
||
cursors on that handle to be closed.
|
||
</p>
|
||
<p>
|
||
|
||
There are only a a few operations which require all open cursors to be closed.
|
||
This include all container <code class="methodname">clear()</code> and
|
||
<code class="methodname">swap()</code> functions, and all versions of
|
||
<code class="methodname">db_vection<>::assign()</code> functions. These
|
||
functions require all cursors to be closed for the database because by default
|
||
they remove all key/data pairs from the database by truncating it.
|
||
</p>
|
||
<p>
|
||
When a function removes all key/data pairs from a database, there are
|
||
two ways it can perform this activity:
|
||
</p>
|
||
<div class="itemizedlist">
|
||
<ul type="disc">
|
||
<li>
|
||
<p>
|
||
The default method is to truncate the database, which is an
|
||
operation that requires all cursors to be closed. As mentioned
|
||
above, it is your responsibility to close cursors opened in other
|
||
threads before performing this operation. Otherwise, the operation
|
||
will fail.
|
||
</p>
|
||
</li>
|
||
<li>
|
||
<p>
|
||
Alternatively, you can specify that the database not be truncated.
|
||
Instead, you can cause dbstl to delete all key/data pairs
|
||
individually, one after another. In this situation,
|
||
open cursors in the database will not cause the delete operations to
|
||
fail. However, due to lock contention, the delete operations might not
|
||
complete until all cursors are closed, which is when all their read locks
|
||
are released.
|
||
</p>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="id3890858"></a>Auto commit support</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
|
||
Dbstl supports auto commit for some of its container's operations. When a dbstl
|
||
container is created using a <code class="classname">Db</code> or <code class="classname">DbEnv</code>
|
||
object, if that object was opened using the <a href="../api_reference/C/envset_flags.html#envset_flags_DB_AUTO_COMMIT" class="olink">DB_AUTO_COMMIT</a> flag, then
|
||
every operation subsequently performed on that object will be
|
||
automatically enclosed in a unique transaction (unless the operation is already in an
|
||
external transaction). This
|
||
is identical to how the Berkeley DB C, C++ and Java APIs behave.
|
||
</p>
|
||
<p>
|
||
Note that only a subset of a container's operations support auto
|
||
commit. This is because those operations that accept or return an
|
||
iterator have to exist in an external transactional context and so
|
||
cannot support auto commit.
|
||
</p>
|
||
<p>
|
||
The dbstl API documentation identifies when a method supports auto
|
||
commit transactions.
|
||
</p>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="id3890555"></a>Database and environment identity checks</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
When a container member function involves another container (for example,
|
||
<code class="methodname">db_vector::swap(self& v2)</code>), the two
|
||
containers involved in the operation must not use the same database.
|
||
Further, if the function is in an external or internal transaction context,
|
||
then both containers must belong
|
||
to the same transactional database environment; Otherwise, the two containers
|
||
can belong to the same database environment, or two different ones.
|
||
</p>
|
||
<p>
|
||
For example, if <code class="methodname">db_vector::swap(self& v2)</code>
|
||
is an auto commit method or it is in an external transaction context,
|
||
then <code class="literal">v2</code> must be in the same transactional database
|
||
environment as this container, because a transaction is started
|
||
internally that must be used by both <code class="literal">v2</code> and this
|
||
container. If this container and the <code class="literal">v2</code> container
|
||
have different database environments, and either of them are using transactions,
|
||
an exception is thrown. This condition is checked in every such member
|
||
function.
|
||
</p>
|
||
<p>
|
||
However, if the function is not in a transactional context,
|
||
then the databases used by these
|
||
containers can be in different environments because in this situation
|
||
dbstl makes no attempt to wrap container operations in a common transaction
|
||
context.
|
||
</p>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="id3890921"></a>Products, constructors and configurations</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
You can use dbstl with all Berkeley DB products (DS, CDS, TDS, and HA).
|
||
Because dbstl is a Berkeley DB interface, all necessary configurations
|
||
for these products are performed using Berkeley DB's standard
|
||
create/open/set APIs.
|
||
</p>
|
||
<p>
|
||
As a result, the dbstl container constructors differ from those of C++
|
||
STL because in dbstl no configuration is supported using the container
|
||
constructors. On the other hand, dbstl container constructors accept
|
||
already opened and configured environment and database handles. They
|
||
also provide functions to retrieve some handle configuration, such as
|
||
key comparison and hash functions, as required by the C++ STL
|
||
specifications.
|
||
</p>
|
||
<p>
|
||
The constructors verify that the handles passed to them are well
|
||
configured. This means they ensure that no banned settings are used, as
|
||
well as ensuring that all required setting are performed. If the
|
||
handles are not well configured, an
|
||
<code class="classname">InvalidArgumentException</code> is thrown.
|
||
</p>
|
||
<p>
|
||
If a container constructor is not passed a database or environment
|
||
handle, an internal anonymous database is created for you by dbstl. This anonymous
|
||
database does not provide data persistence.
|
||
</p>
|
||
</div>
|
||
</div>
|
||
<div class="navfooter">
|
||
<hr />
|
||
<table width="100%" summary="Navigation footer">
|
||
<tr>
|
||
<td width="40%" align="left"><a accesskey="p" href="stl_examples.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_db_advanced_usage.html">Next</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="40%" align="left" valign="top">Dbstl examples </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="h" href="index.html">Home</a>
|
||
</td>
|
||
<td width="40%" align="right" valign="top"> Using advanced Berkeley DB features with dbstl</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html>
|