mirror of
https://github.com/yasuhirokimura/db18
synced 2026-06-08 18:29:23 +00:00
Yasuhiro KIMURA
170 lines
8.6 KiB
HTML
170 lines
8.6 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>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>
|