mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-16 09:06:25 +00:00
129 lines
7.5 KiB
HTML
129 lines
7.5 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 15. 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 11.2.5.3</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 15.
|
||
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>
|