diff options
Diffstat (limited to 'docs/programmer_reference/program_mt.html')
| -rw-r--r-- | docs/programmer_reference/program_mt.html | 156 |
1 files changed, 98 insertions, 58 deletions
diff --git a/docs/programmer_reference/program_mt.html b/docs/programmer_reference/program_mt.html index 7c8c4443..4bb44a64 100644 --- a/docs/programmer_reference/program_mt.html +++ b/docs/programmer_reference/program_mt.html @@ -14,7 +14,7 @@ <body> <div xmlns="" class="navheader"> <div class="libver"> - <p>Library Version 11.2.5.3</p> + <p>Library Version 12.1.6.1</p> </div> <table width="100%" summary="Navigation header"> <tr> @@ -22,9 +22,7 @@ </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> + <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> @@ -38,73 +36,115 @@ </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> + <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> + <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> - 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> + 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> + <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> + <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> + <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 /> |