1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
|
<!--$Id: mt.html,v 1.1.1.1 2003/11/20 22:14:15 toshok Exp $-->
<!--Copyright 1997-2002 by Sleepycat Software, Inc.-->
<!--All rights reserved.-->
<!--See the file LICENSE for redistribution information.-->
<html>
<head>
<title>Berkeley DB Reference Guide: Multithreaded applications</title>
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
<meta name="keywords" content="embedded,database,programmatic,toolkit,b+tree,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,java,C,C++">
</head>
<body bgcolor=white>
<a name="2"><!--meow--></a>
<table width="100%"><tr valign=top>
<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Programmer Notes</dl></h3></td>
<td align=right><a href="../../ref/program/environ.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/scope.html"><img src="../../images/next.gif" alt="Next"></a>
</td></tr></table>
<p>
<h1 align=center>Multithreaded applications</h1>
<p>Berkeley DB fully supports multithreaded applications. The Berkeley DB library is
not itself multithreaded, as it was deliberately architected to not use
threads internally because of the portability problems it 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><ol>
<p><li>The <a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag must be specified to the <a href="../../api_c/env_open.html">DB_ENV->open</a>
and <a href="../../api_c/db_open.html">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_c/env_open.html#DB_THREAD">DB_THREAD</a> flag inconsistently may result in database corruption.
<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_c/env_open.html#DB_THREAD">DB_THREAD</a> flag
was specified.
<p>Only a single thread may call the <a href="../../api_c/env_close.html">DB_ENV->close</a> or <a href="../../api_c/db_close.html">DB->close</a> methods
for a returned environment or database handle.
<p>No other Berkeley DB handles are free-threaded; for example, cursors and
transactions may not span threads because their returned handles are
not free-threaded.
<p><li>When using the non-cursor Berkeley DB calls to retrieve key/data items (for
example, <a href="../../api_c/db_get.html">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_c/db_class.html">DB</a>
handle returned by <a href="../../api_c/db_open.html">DB->open</a>. This includes <b>any</b> use of
the returned <a href="../../api_c/db_class.html">DB</a> handle, including by another thread within the
process.
<p>For this reason, if the <a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> handle was specified to the
<a href="../../api_c/db_open.html">DB->open</a> method, either <a href="../../api_c/dbt_class.html#DB_DBT_MALLOC">DB_DBT_MALLOC</a>, <a href="../../api_c/dbt_class.html#DB_DBT_REALLOC">DB_DBT_REALLOC</a>,
or <a href="../../api_c/dbt_class.html#DB_DBT_USERMEM">DB_DBT_USERMEM</a> must be specified in the <a href="../../api_c/dbt_class.html">DBT</a> when
performing any non-cursor key or data retrieval.
<p><li>Transactions may not span threads. Each transaction must begin and end
in the same thread, and each transaction may be used only by a single
thread.
<p>Cursors may not span transactions or threads. Each cursor must be
allocated and deallocated within the same transaction and within
the same thread.
<p><li>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>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 will be more efficient to explicitly yield the processor to
another thread.
<p>It is possible to specify a yield function on an per-application basis.
See <a href="../../api_c/set_func_yield.html">db_env_set_func_yield</a> for more information.
<p>It is possible to specify the number of attempts that will be made to
acquire the mutex before waiting. See <a href="../../api_c/env_set_tas_spins.html">DB_ENV->set_tas_spins</a> for
more information.
</ol>
<table width="100%"><tr><td><br></td><td align=right><a href="../../ref/program/environ.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../../reftoc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../../ref/program/scope.html"><img src="../../images/next.gif" alt="Next"></a>
</td></tr></table>
<p><font size=1><a href="http://www.sleepycat.com">Copyright Sleepycat Software</a></font>
</body>
</html>
|
