1<!--$Id: mt.so,v 10.48 2005/07/20 16:34:05 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB Reference Guide: Multithreaded applications</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<a name="2"><!--meow--></a> 12<table width="100%"><tr valign=top> 13<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Programmer Notes</dl></b></td> 14<td align=right><a href="../program/environ.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../program/scope.html"><img src="../../images/next.gif" alt="Next"></a> 15</td></tr></table> 16<p align=center><b>Multithreaded applications</b></p> 17<p>Berkeley DB fully supports multithreaded applications. The Berkeley DB library is 18not itself multithreaded, and was deliberately architected to not use 19threads internally because of the portability problems that would 20introduce. Database environment and database object handles returned 21from Berkeley DB library functions are free-threaded. No other object handles 22returned from the Berkeley DB library are free-threaded. The following rules 23should be observed when using threads to access the Berkeley DB library:</p> 24<ol> 25<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> 26and <a href="../../api_c/db_open.html">DB->open</a> methods if the Berkeley DB handles returned by those interfaces 27will be used in the context of more than one thread. Setting the 28<a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag inconsistently may result in database corruption. 29<p>Threading is assumed in the Java API, so no special flags are required; 30and Berkeley DB functions will always behave as if the <a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> flag 31was specified.</p> 32<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 33for a returned environment or database handle.</p> 34<p>No other Berkeley DB handles are free-threaded.</p> 35<p><li>When using the non-cursor Berkeley DB calls to retrieve key/data items (for 36example, <a href="../../api_c/db_get.html">DB->get</a>), the memory to which the pointer stored into 37the Dbt refers is valid only until the next call using the <a href="../../api_c/db_class.html">DB</a> 38handle returned by <a href="../../api_c/db_open.html">DB->open</a>. This includes <b>any</b> use of 39the returned <a href="../../api_c/db_class.html">DB</a> handle, including by another thread within the 40process. 41<p>For this reason, if the <a href="../../api_c/env_open.html#DB_THREAD">DB_THREAD</a> handle was specified to the 42<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>, 43or <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 44performing any non-cursor key or data retrieval.</p> 45<p><li>Cursors may not span transactions. Each cursor must be 46allocated and deallocated within the same transaction. 47<p>Transactions and cursors may span threads, but only serially, that is, 48the application must serialize access to the <a href="../../api_c/txn_class.html">DB_TXN</a> and 49<a href="../../api_c/dbc_class.html">DBC</a> handles. In the case of nested transactions, since all 50child transactions are part of the same parent transaction, they must observe 51the same constraints. That is, children may execute in different threads 52only if each child executes serially.</p> 53<p><li>User-level synchronization mutexes must have been implemented for the 54compiler/architecture combination. Attempting to specify the DB_THREAD 55flag will fail if fast mutexes are not available. 56<p>If blocking mutexes are available (for example POSIX pthreads), they 57will be used. Otherwise, the Berkeley DB library will make a system call to 58pause for some amount of time when it is necessary to wait on a lock. 59This may not be optimal, especially in a thread-only environment, in 60which it is usually more efficient to explicitly yield the processor to 61another thread.</p> 62<p>It is possible to specify a yield function on an per-application basis. 63See <a href="../../api_c/set_func_yield.html">db_env_set_func_yield</a> for more information.</p> 64<p>It is possible to specify the number of attempts that will be made to 65acquire the mutex before waiting. See <a href="../../api_c/mutex_set_tas_spins.html">DB_ENV->mutex_set_tas_spins</a> for 66more information.</p> 67</ol> 68<p>When creating multiple databases in a single physical file, multithreaded 69programs may have additional requirements. For more information, see 70<a href="../../ref/am/opensub.html">Opening multiple databases in a single 71file.</a></p> 72<table width="100%"><tr><td><br></td><td align=right><a href="../program/environ.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../program/scope.html"><img src="../../images/next.gif" alt="Next"></a> 73</td></tr></table> 74<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 75</body> 76</html> 77
