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>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="program.html" title="Chapter 16. Programmer Notes" />
<link rel="prev" href="program_environ.html" title="Environment variables" />
<link rel="next" href="program_scope.html" title="Berkeley DB handles" />
</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">Multithreaded applications</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="program_environ.html">Prev</a> </td>
<th width="60%" align="center">Chapter 16. Programmer Notes </th>
<td width="20%" align="right"> <a accesskey="n" href="program_scope.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="program_mt"></a>Multithreaded applications</h2>
</div>
</div>
</div>
<p>
Berkeley DB fully supports multithreaded applications. The
Berkeley DB library is not itself multithreaded, and was
deliberately architected to not use threads internally because
of the portability problems that would introduce. Database
environment and database object handles returned from Berkeley
DB library functions are free-threaded. No other object
handles returned from the Berkeley DB library are
free-threaded. The following rules should be observed when
using threads to access the Berkeley DB library:
</p>
<div class="orderedlist">
<ol type="1">
<li>
<p>
The <a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> flag must be specified to the
<a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> and <a href="../api_reference/C/dbopen.html" class="olink">DB->open()</a> methods if the Berkeley DB
handles returned by those interfaces will be used in
the context of more than one thread. Setting the
<a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> flag inconsistently may result in database
corruption.
</p>
<p>
Threading is assumed in the Java API, so no special
flags are required; and Berkeley DB functions will
always behave as if the <a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> flag was
specified.
</p>
<p>
Only a single thread may call the <a href="../api_reference/C/envclose.html" class="olink">DB_ENV->close()</a> or
<a href="../api_reference/C/dbclose.html" class="olink">DB->close()</a> methods for a returned environment or
database handle.
</p>
<p>
No other Berkeley DB handles are
free-threaded.
</p>
</li>
<li>
<p>
When using the non-cursor Berkeley DB calls to
retrieve key/data items (for example, <a href="../api_reference/C/dbget.html" class="olink">DB->get()</a>), the
memory to which the pointer stored into the Dbt refers
is valid only until the next call using the <a href="../api_reference/C/db.html" class="olink">DB</a>
handle returned by <a href="../api_reference/C/dbopen.html" class="olink">DB->open()</a>. This includes <span class="bold"><strong>any</strong></span> use of the returned
<a href="../api_reference/C/db.html" class="olink">DB</a> handle, including by another thread within the
process.
</p>
<p>
For this reason, if the <a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> handle was
specified to the <a href="../api_reference/C/dbopen.html" class="olink">DB->open()</a> method, either
<a href="../api_reference/C/dbt.html#dbt_DB_DBT_MALLOC" class="olink">DB_DBT_MALLOC</a>, <a href="../api_reference/C/dbt.html#dbt_DB_DBT_REALLOC" class="olink">DB_DBT_REALLOC</a> or <a href="../api_reference/C/dbt.html#dbt_DB_DBT_USERMEM" class="olink">DB_DBT_USERMEM</a>
must be specified in the <a href="../api_reference/C/dbt.html" class="olink">DBT</a> when performing any
non-cursor key or data retrieval.
</p>
</li>
<li>
<p>
Cursors may not span transactions. Each cursor must
be allocated and deallocated within the same
transaction.
</p>
<p>
Transactions and cursors may span threads, but only
serially, that is, the application must serialize
access to the <a href="../api_reference/C/txn.html" class="olink">TXN</a> and <a href="../api_reference/C/dbc.html" class="olink">DBC</a> handles. In the case of
nested transactions, since all child transactions are
part of the same parent transaction, they must observe
the same constraints. That is, children may execute in
different threads only if each child executes
serially.
</p>
</li>
<li>
<p>
User-level synchronization mutexes must have been
implemented for the compiler/architecture combination.
Attempting to specify the DB_THREAD flag will fail if
fast mutexes are not available.
</p>
<p>
If blocking mutexes are available (for example POSIX
pthreads), they will be used. Otherwise, the Berkeley
DB library will make a system call to pause for some
amount of time when it is necessary to wait on a lock.
This may not be optimal, especially in a thread-only
environment, in which it is usually more efficient to
explicitly yield the processor to another
thread.
</p>
<p>
It is possible to specify a yield function on an
per-application basis. See <a href="../api_reference/C/db_env_set_func_yield.html" class="olink">db_env_set_func_yield</a> for more
information.
</p>
<p>
It is possible to specify the number of attempts
that will be made to acquire the mutex before waiting.
See <a href="../api_reference/C/mutexset_tas_spins.html" class="olink">DB_ENV->mutex_set_tas_spins()</a> for more information.
</p>
</li>
</ol>
</div>
<p>
When creating multiple databases in a single physical file,
multithreaded programs may have additional requirements. For
more information, see <a class="xref" href="am_opensub.html" title="Opening multiple databases in a single file">Opening multiple databases in a
single file</a>
</p>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="program_environ.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="program.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="program_scope.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">Environment variables </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Berkeley DB handles</td>
</tr>
</table>
</div>
</body>
</html>
Sindbad File Manager Version 1.0, Coded By Sindbad EG ~ The Terrorists