diff options
| author | Lorry Tar Creator <lorry-tar-importer@baserock.org> | 2015-02-17 17:25:57 +0000 |
|---|---|---|
| committer | <> | 2015-03-17 16:26:24 +0000 |
| commit | 780b92ada9afcf1d58085a83a0b9e6bc982203d1 (patch) | |
| tree | 598f8b9fa431b228d29897e798de4ac0c1d3d970 /docs/programmer_reference/stl_mt_usage.html | |
| parent | 7a2660ba9cc2dc03a69ddfcfd95369395cc87444 (diff) | |
| download | berkeleydb-master.tar.gz | |
Diffstat (limited to 'docs/programmer_reference/stl_mt_usage.html')
| -rw-r--r-- | docs/programmer_reference/stl_mt_usage.html | 242 |
1 files changed, 133 insertions, 109 deletions
diff --git a/docs/programmer_reference/stl_mt_usage.html b/docs/programmer_reference/stl_mt_usage.html index f4f4f254..ce60d95b 100644 --- a/docs/programmer_reference/stl_mt_usage.html +++ b/docs/programmer_reference/stl_mt_usage.html @@ -14,11 +14,12 @@ <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> - <th colspan="3" align="center">Using dbstl in multithreaded applications</th> + <th colspan="3" align="center">Using dbstl in multithreaded + applications</th> </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="stl_txn_usage.html">Prev</a> </td> @@ -32,168 +33,191 @@ <div class="titlepage"> <div> <div> - <h2 class="title" style="clear: both"><a id="stl_mt_usage"></a>Using dbstl in multithreaded applications</h2> + <h2 class="title" style="clear: both"><a id="stl_mt_usage"></a>Using dbstl in multithreaded + applications</h2> </div> </div> </div> - <p> - Multithreaded use of dbstl must obey the following guidelines: -</p> + <p> + Multithreaded use of dbstl must obey the following + guidelines: + </p> <div class="orderedlist"> <ol type="1"> <li> <p> - For a few non-standard platforms, you must first configure dbstl for that - platform, but usually the configure script will - detect the applicable thread local storage (TLS) modifier to use, and - then use it. If no appropriate TLS is found, the pthread TLS API is used. -</p> + For a few non-standard platforms, you must first + configure dbstl for that platform, but usually the + configure script will detect the applicable thread + local storage (TLS) modifier to use, and then use it. + If no appropriate TLS is found, the pthread TLS API is + used. + </p> </li> <li> <p> - Perform all initializations in a single thread. - <code class="methodname">dbstl::dbstl_startup()</code> should be called - mutually exclusive in a single thread before using dbstl. If dbstl is - used in only a single thread, this function does not need to be called. -</p> - <p> - If necessary, callback functions for a complex type T must be - registered to the singleton of - DbstlElemTraits<T> before any container related to T (for - example, <code class="literal">db_vector<T></code>), is used, and certain - isolation may be required among multiple threads. The best way to do - this is to register all callback function pointers into the singleton - in a single thread before making use of the containers. -</p> + Perform all initializations in a single thread. + <code class="methodname">dbstl::dbstl_startup()</code> + should be called mutually exclusive in a single thread + before using dbstl. If dbstl is used in only a single + thread, this function does not need to be called. + </p> + <p> + If necessary, callback functions for a complex type + T must be registered to the singleton of + DbstlElemTraits<T> before any container related + to T (for example, + <code class="literal">db_vector<T></code>), is used, + and certain isolation may be required among multiple + threads. The best way to do this is to register all + callback function pointers into the singleton in a + single thread before making use of the containers. + </p> <p> - All container cursor open flags and auto commit transaction - begin/commit flags must be set in a single thread before storing - objects into or reading objects from the container. -</p> + All container cursor open flags and auto commit + transaction begin/commit flags must be set in a single + thread before storing objects into or reading objects + from the container. + </p> </li> <li> <p> - Environment and database handles can optionally be shared across - threads. If handles are shared, they must be registered in each thread - that is using the handle (either directly, or indirectly using the - containers that own the handles). You do this using the - <code class="function">dbstl::register_db()</code> and - <code class="function">dbstl::register_db_env()</code> functions. Note that - these functions are not necessary if the current thread called - <code class="function">dbstl::open_db()</code> or - <code class="function">dbstl::open_env()</code> for the handle that is being - shared. This is because the open functions automatically register the - handle for you. -</p> - <p> - Note that the get/set functions that provide access to container data - members are not mutex-protected because these data members are supposed - to be set only once at container object initialization. Applications - wishing to modify them after initialization must supply their own - protection. -</p> + Environment and database handles can optionally be + shared across threads. If handles are shared, they + must be registered in each thread that is using the + handle (either directly, or indirectly using the + containers that own the handles). You do this using + the <code class="function">dbstl::register_db()</code> and + <code class="function">dbstl::register_db_env()</code> + functions. Note that these functions are not necessary + if the current thread called + <code class="function">dbstl::open_db()</code> or + <code class="function">dbstl::open_env()</code> for the + handle that is being shared. This is because the open + functions automatically register the handle for you. + </p> + <p> + Note that the get/set functions that provide access + to container data members are not mutex-protected + because these data members are supposed to be set only + once at container object initialization. Applications + wishing to modify them after initialization must + supply their own protection. + </p> </li> <li> <p> - While container objects can be shared between multiple threads, - iterators and transactions can not be shared. -</p> + While container objects can be shared between + multiple threads, iterators and transactions can not + be shared. + </p> </li> <li> <p> - Set the <span class="bold"><strong>directdb_get</strong></span> parameter of the - container <code class="methodname">begin()</code> method to - <code class="literal">true</code> in order to guarantee that referenced key/data - pairs are always obtained from the database and not from an iterator's - cached value. (This is the default behavior.) You should do this - because otherwise a rare situation may occur. Given db_vector_iterator - i1 and i2 used in the same iteration, setting *i1 = new_value will not - update i2, and *i2 will return the original value. -</p> + Set the <span class="bold"><strong>directdb_get</strong></span> parameter of the + container <code class="methodname">begin()</code> method to + <code class="literal">true</code> in order to guarantee that + referenced key/data pairs are always obtained from the + database and not from an iterator's cached value. + (This is the default behavior.) You should do this + because otherwise a rare situation may occur. Given + db_vector_iterator i1 and i2 used in the same + iteration, setting *i1 = new_value will not update i2, + and *i2 will return the original value. + </p> </li> <li> - <p> - If using a CDS database, only const iterators or read-only non-const - iterators should be used for read only iterations. Otherwise, when - multiple threads try to open read-write iterators at the same time, - performance is greatly degraded because CDS only supports one write cursor - open at any moment. The use of read-only iterators is good practice - in general because dbstl contains internal optimizations for read-only - iterators. -</p> - <p> - To create a read-only iterator, do one of the following: -</p> + <p> + If using a CDS database, only const iterators or + read-only non-const iterators should be used for read + only iterations. Otherwise, when multiple threads try + to open read-write iterators at the same time, + performance is greatly degraded because CDS only + supports one write cursor open at any moment. The use + of read-only iterators is good practice in general + because dbstl contains internal optimizations for + read-only iterators. + </p> + <p> + To create a read-only iterator, do one of the + following: + </p> <div class="itemizedlist"> <ul type="disc"> <li> - <p> - Use a <code class="literal">const</code> reference to the container - object, then call the container's - <code class="methodname">begin()</code> method using the const - reference, and then store the return value from the - <code class="methodname">begin()</code> method in a - <code class="methodname">db_vector::const_iterator</code>. - </p> + <p> + Use a <code class="literal">const</code> reference to + the container object, then call the + container's <code class="methodname">begin()</code> + method using the const reference, and then + store the return value from the + <code class="methodname">begin()</code> method in + a + <code class="methodname">db_vector::const_iterator</code>. + </p> </li> <li> - <p> - If you are using a non-const container object, then simply - pass <code class="literal">true</code> to the - <span class="bold"><strong>readonly</strong></span> parameter of the - non-const <code class="methodname">begin()</code> method. - </p> + <p> + If you are using a non-const container + object, then simply pass + <code class="literal">true</code> to the <span class="bold"><strong>readonly</strong></span> parameter + of the non-const + <code class="methodname">begin()</code> method. + </p> </li> </ul> </div> </li> <li> - <p> - When using DS, CDS or TDS, enable the locking subsystem by passing the - <a href="../api_reference/C/envopen.html#envopen_DB_INIT_LOCK" class="olink">DB_INIT_LOCK</a> flag to <code class="methodname">DbEnv::open()</code>. -</p> + <p> + When using DS, CDS or TDS, enable the locking + subsystem by passing the <a href="../api_reference/C/envopen.html#envopen_DB_INIT_LOCK" class="olink">DB_INIT_LOCK</a> flag to + <code class="methodname">DbEnv::open()</code>. + </p> </li> <li> - <p> - Perform portable thread synchronization within a process by calling the - following functions. These are all global functions in the "dbstl" name - space: -</p> + <p> + Perform portable thread synchronization within a + process by calling the following functions. These are + all global functions in the "dbstl" name space: + </p> <table class="simplelist" border="0" summary="Simple list"> <tr> <td> - <code class="function">db_mutex_t alloc_mutex();</code> + <code class="function">db_mutex_t alloc_mutex();</code> </td> </tr> <tr> <td> - <code class="function">int lock_mutex(db_mutex_t);</code> + <code class="function">int lock_mutex(db_mutex_t);</code> </td> </tr> <tr> <td> - <code class="function">int unlock_mutex(db_mutex_t);</code> + <code class="function">int unlock_mutex(db_mutex_t);</code> </td> </tr> <tr> <td> - <code class="function">void free_mutex(db_mutex_t);</code> + <code class="function">void free_mutex(db_mutex_t);</code> </td> </tr> </table> - <p> - These functions use an internal dbstl environment's mutex functionality - to synchronize. As a result, the synchronization is portable across all - platforms supported by Berkeley DB. -</p> + <p> + These functions use an internal dbstl environment's + mutex functionality to synchronize. As a result, the + synchronization is portable across all platforms + supported by Berkeley DB. + </p> </li> </ol> </div> - <p> - The <code class="classname">WorkerThread</code> class provides example code - demonstrating the use of dbstl in multi-threaded applications. You can - find this class implemented in the dbstl test suite. -</p> + <p> + The <code class="classname">WorkerThread</code> class provides + example code demonstrating the use of dbstl in multi-threaded + applications. You can find this class implemented in the dbstl + test suite. + </p> </div> <div class="navfooter"> <hr /> |