mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-16 17:16:25 +00:00
219 lines
9.1 KiB
HTML
219 lines
9.1 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 dbstl in multithreaded applications</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_txn_usage.html" title="Using transactions in dbstl" />
|
|||
|
|
<link rel="next" href="stl_primitive_rw.html" title="Working with primitive types" />
|
|||
|
|
</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">Using dbstl in multithreaded applications</th>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td width="20%" align="left"><a accesskey="p" href="stl_txn_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_primitive_rw.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_mt_usage"></a>Using dbstl in multithreaded applications</h2>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
</div>
|
|||
|
|
<p>
|
|||
|
|
Multithreaded use of dbstl must obey the following guidelines:
|
|||
|
|
</p>
|
|||
|
|
<div class="orderedlist">
|
|||
|
|
<ol type="1">
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
For a few non-standard platforms, you must first configure dbstl for that
|
|||
|
|
platform, but usually the configure script will
|
|||
|
|
detect the applicable thread local storage (TLS) modifier to use, and
|
|||
|
|
then use it. If no appropriate TLS is found, the pthread TLS API is used.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
Perform all initializations in a single thread.
|
|||
|
|
<code class="methodname">dbstl::dbstl_startup()</code> should be called
|
|||
|
|
mutually exclusive in a single thread before using dbstl. If dbstl is
|
|||
|
|
used in only a single thread, this function does not need to be called.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
If necessary, callback functions for a complex type T must be
|
|||
|
|
registered to the singleton of
|
|||
|
|
DbstlElemTraits<T> before any container related to T (for
|
|||
|
|
example, <code class="literal">db_vector<T></code>), is used, and certain
|
|||
|
|
isolation may be required among multiple threads. The best way to do
|
|||
|
|
this is to register all callback function pointers into the singleton
|
|||
|
|
in a single thread before making use of the containers.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
All container cursor open flags and auto commit transaction
|
|||
|
|
begin/commit flags must be set in a single thread before storing
|
|||
|
|
objects into or reading objects from the container.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
Environment and database handles can optionally be shared across
|
|||
|
|
threads. If handles are shared, they must be registered in each thread
|
|||
|
|
that is using the handle (either directly, or indirectly using the
|
|||
|
|
containers that own the handles). You do this using the
|
|||
|
|
<code class="function">dbstl::register_db()</code> and
|
|||
|
|
<code class="function">dbstl::register_db_env()</code> functions. Note that
|
|||
|
|
these functions are not necessary if the current thread called
|
|||
|
|
<code class="function">dbstl::open_db()</code> or
|
|||
|
|
<code class="function">dbstl::open_env()</code> for the handle that is being
|
|||
|
|
shared. This is because the open functions automatically register the
|
|||
|
|
handle for you.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
Note that the get/set functions that provide access to container data
|
|||
|
|
members are not mutex-protected because these data members are supposed
|
|||
|
|
to be set only once at container object initialization. Applications
|
|||
|
|
wishing to modify them after initialization must supply their own
|
|||
|
|
protection.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
While container objects can be shared between multiple threads,
|
|||
|
|
iterators and transactions can not be shared.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
Set the <span class="bold"><strong>directdb_get</strong></span> parameter of the
|
|||
|
|
container <code class="methodname">begin()</code> method to
|
|||
|
|
<code class="literal">true</code> in order to guarantee that referenced key/data
|
|||
|
|
pairs are always obtained from the database and not from an iterator's
|
|||
|
|
cached value. (This is the default behavior.) You should do this
|
|||
|
|
because otherwise a rare situation may occur. Given db_vector_iterator
|
|||
|
|
i1 and i2 used in the same iteration, setting *i1 = new_value will not
|
|||
|
|
update i2, and *i2 will return the original value.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
If using a CDS database, only const iterators or read-only non-const
|
|||
|
|
iterators should be used for read only iterations. Otherwise, when
|
|||
|
|
multiple threads try to open read-write iterators at the same time,
|
|||
|
|
performance is greatly degraded because CDS only supports one write cursor
|
|||
|
|
open at any moment. The use of read-only iterators is good practice
|
|||
|
|
in general because dbstl contains internal optimizations for read-only
|
|||
|
|
iterators.
|
|||
|
|
</p>
|
|||
|
|
<p>
|
|||
|
|
To create a read-only iterator, do one of the following:
|
|||
|
|
</p>
|
|||
|
|
<div class="itemizedlist">
|
|||
|
|
<ul type="disc">
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
Use a <code class="literal">const</code> reference to the container
|
|||
|
|
object, then call the container's
|
|||
|
|
<code class="methodname">begin()</code> method using the const
|
|||
|
|
reference, and then store the return value from the
|
|||
|
|
<code class="methodname">begin()</code> method in a
|
|||
|
|
<code class="methodname">db_vector::const_iterator</code>.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
If you are using a non-const container object, then simply
|
|||
|
|
pass <code class="literal">true</code> to the
|
|||
|
|
<span class="bold"><strong>readonly</strong></span> parameter of the
|
|||
|
|
non-const <code class="methodname">begin()</code> method.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
</ul>
|
|||
|
|
</div>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
When using DS, CDS or TDS, enable the locking subsystem by passing the
|
|||
|
|
<a href="../api_reference/C/envopen.html#envopen_DB_INIT_LOCK" class="olink">DB_INIT_LOCK</a> flag to <code class="methodname">DbEnv::open()</code>.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
<li>
|
|||
|
|
<p>
|
|||
|
|
Perform portable thread synchronization within a process by calling the
|
|||
|
|
following functions. These are all global functions in the "dbstl" name
|
|||
|
|
space:
|
|||
|
|
</p>
|
|||
|
|
<table class="simplelist" border="0" summary="Simple list">
|
|||
|
|
<tr>
|
|||
|
|
<td>
|
|||
|
|
<code class="function">db_mutex_t alloc_mutex();</code>
|
|||
|
|
</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td>
|
|||
|
|
<code class="function">int lock_mutex(db_mutex_t);</code>
|
|||
|
|
</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td>
|
|||
|
|
<code class="function">int unlock_mutex(db_mutex_t);</code>
|
|||
|
|
</td>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td>
|
|||
|
|
<code class="function">void free_mutex(db_mutex_t);</code>
|
|||
|
|
</td>
|
|||
|
|
</tr>
|
|||
|
|
</table>
|
|||
|
|
<p>
|
|||
|
|
These functions use an internal dbstl environment's mutex functionality
|
|||
|
|
to synchronize. As a result, the synchronization is portable across all
|
|||
|
|
platforms supported by Berkeley DB.
|
|||
|
|
</p>
|
|||
|
|
</li>
|
|||
|
|
</ol>
|
|||
|
|
</div>
|
|||
|
|
<p>
|
|||
|
|
The <code class="classname">WorkerThread</code> class provides example code
|
|||
|
|
demonstrating the use of dbstl in multi-threaded applications. You can
|
|||
|
|
find this class implemented in the dbstl test suite.
|
|||
|
|
</p>
|
|||
|
|
</div>
|
|||
|
|
<div class="navfooter">
|
|||
|
|
<hr />
|
|||
|
|
<table width="100%" summary="Navigation footer">
|
|||
|
|
<tr>
|
|||
|
|
<td width="40%" align="left"><a accesskey="p" href="stl_txn_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_primitive_rw.html">Next</a></td>
|
|||
|
|
</tr>
|
|||
|
|
<tr>
|
|||
|
|
<td width="40%" align="left" valign="top">Using transactions in dbstl </td>
|
|||
|
|
<td width="20%" align="center">
|
|||
|
|
<a accesskey="h" href="index.html">Home</a>
|
|||
|
|
</td>
|
|||
|
|
<td width="40%" align="right" valign="top"> Working with primitive types </td>
|
|||
|
|
</tr>
|
|||
|
|
</table>
|
|||
|
|
</div>
|
|||
|
|
</body>
|
|||
|
|
</html>
|