Sindbad~EG File Manager
<?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 18.1.40</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>
Sindbad File Manager Version 1.0, Coded By Sindbad EG ~ The Terrorists