1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>Using dbstl in multithreaded applications</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" /> 10 <link rel="up" href="stl.html" title="Chapter��7.��Standard Template Library API" /> 11 <link rel="prev" href="stl_txn_usage.html" title="Using transactions in dbstl" /> 12 <link rel="next" href="stl_primitive_rw.html" title="Working with primitive types" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Using dbstl in multithreaded applications</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="stl_txn_usage.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��7.��Standard Template Library API</th> 23 <td width="20%" align="right">��<a accesskey="n" href="stl_primitive_rw.html">Next</a></td> 24 </tr> 25 </table> 26 <hr /> 27 </div> 28 <div class="sect1" lang="en" xml:lang="en"> 29 <div class="titlepage"> 30 <div> 31 <div> 32 <h2 class="title" style="clear: both"><a id="stl_mt_usage"></a>Using dbstl in multithreaded applications</h2> 33 </div> 34 </div> 35 </div> 36 <p> 37 Multithreaded use of dbstl must obey the following guidelines: 38</p> 39 <div class="orderedlist"> 40 <ol type="1"> 41 <li> 42 <p> 43 For a few non-standard platforms, you must first configure dbstl for that 44 platform as described below. Usually the configure script will 45 detect the applicable thread local storage (TLS) modifier to use, and 46 then use it. If no appropriate TLS is found, the pthread TLS API is used. 47</p> 48 <p> 49 On HP Tru64, if you are not using a gcc compiler, #define HPTru64 50 before #include'ing any dbstl container header files. 51</p> 52 </li> 53 <li> 54 <p> 55 Perform all initializations in a single thread. 56 <code class="methodname">dbstl::dbstl_startup()</code> should be called 57 mutually exclusive in a single thread before using dbstl. If dbstl is 58 used in only a single thread, this function does not need to be called. 59</p> 60 <p> 61 If necessary, callback functions for a complex type T must be 62 registered to the singleton of 63 DbstlElemTraits<T> before any container related to T (for 64 example, <code class="literal">db_vector<T></code>), is used, and certain 65 isolation may be required among multiple threads. The best way to do 66 this is to register all callback function pointers into the singleton 67 in a single thread before making use of the containers. 68</p> 69 <p> 70 All container cursor open flags and auto commit transaction 71 begin/commit flags must be set in a single thread before storing 72 objects into or reading objects from the container. 73</p> 74 </li> 75 <li> 76 <p> 77 Environment and database handles can optionally be shared across 78 threads. If handles are shared, they must be registered in each thread 79 that is using the handle (either directly, or indirectly using the 80 containers that own the handles). You do this using the 81 <code class="function">dbstl::register_db()</code> and 82 <code class="function">dbstl::register_db_env()</code> functions. Note that 83 these functions are not necessary if the current thread called 84 <code class="function">dbstl::open_db()</code> or 85 <code class="function">dbstl::open_env()</code> for the handle that is being 86 shared. This is because the open functions automatically register the 87 handle for you. 88</p> 89 <p> 90 Note that the get/set functions that provide access to container data 91 members are not mutex-protected because these data members are supposed 92 to be set only once at container object initialization. Applications 93 wishing to modify them after initialization must supply their own 94 protection. 95</p> 96 </li> 97 <li> 98 <p> 99 While container objects can be shared between multiple threads, 100 iterators and transactions can not be shared. 101</p> 102 </li> 103 <li> 104 <p> 105 Set the <span class="bold"><strong>directdb_get</strong></span> parameter of the 106 container <code class="methodname">begin()</code> method to 107 <code class="literal">true</code> in order to guarantee that referenced key/data 108 pairs are always obtained from the database and not from an iterator's 109 cached value. (This is the default behavior.) You should do this 110 because otherwise a rare situation may occur. Given db_vector_iterator 111 i1 and i2 used in the same iteration, setting *i1 = new_value will not 112 update i2, and *i2 will return the original value. 113</p> 114 </li> 115 <li> 116 <p> 117 If using a CDS database, only const iterators or read-only non-const 118 iterators should be used for read only iterations. Otherwise, when 119 multiple threads try to open read-write iterators at the same time, 120 performance is greatly degraded because CDS only supports one write cursor 121 open at any moment. The use of read-only iterators is good practice 122 in general because dbstl contains internal optimizations for read-only 123 iterators. 124</p> 125 <p> 126 To create a read-only iterator, do one of the following: 127</p> 128 <div class="itemizedlist"> 129 <ul type="disc"> 130 <li> 131 <p> 132 Use a <code class="literal">const</code> reference to the container 133 object, then call the container's 134 <code class="methodname">begin()</code> method using the const 135 reference, and then store the return value from the 136 <code class="methodname">begin()</code> method in a 137 <code class="methodname">db_vector::const_iterator</code>. 138 </p> 139 </li> 140 <li> 141 <p> 142 If you are using a non-const container object, then simply 143 pass <code class="literal">true</code> to the 144 <span class="bold"><strong>readonly</strong></span> parameter of the 145 non-const <code class="methodname">begin()</code> method. 146 </p> 147 </li> 148 </ul> 149 </div> 150 </li> 151 <li> 152 <p> 153 When using DS, CDS or TDS, enable the locking subsystem by passing the 154 <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>. 155</p> 156 </li> 157 <li> 158 <p> 159 Perform portable thread synchronization within a process by calling the 160 following functions. These are all global functions in the "dbstl" name 161 space: 162</p> 163 <table class="simplelist" border="0" summary="Simple list"> 164 <tr> 165 <td> 166 <code class="function">db_mutex_t alloc_mutex();</code> 167 </td> 168 </tr> 169 <tr> 170 <td> 171 <code class="function">int lock_mutex(db_mutex_t);</code> 172 </td> 173 </tr> 174 <tr> 175 <td> 176 <code class="function">int unlock_mutex(db_mutex_t);</code> 177 </td> 178 </tr> 179 <tr> 180 <td> 181 <code class="function">void free_mutex(db_mutex_t);</code> 182 </td> 183 </tr> 184 </table> 185 <p> 186 These functions use an internal dbstl environment's mutex functionality 187 to synchronize. As a result, the synchronization is portable across all 188 platforms supported by Berkeley DB. 189</p> 190 </li> 191 </ol> 192 </div> 193 <p> 194 The <code class="classname">WorkerThread</code> class provides example code 195 demonstrating the use of dbstl in multi-threaded applications. You can 196 find this class implemented in the dbstl test suite. 197</p> 198 </div> 199 <div class="navfooter"> 200 <hr /> 201 <table width="100%" summary="Navigation footer"> 202 <tr> 203 <td width="40%" align="left"><a accesskey="p" href="stl_txn_usage.html">Prev</a>��</td> 204 <td width="20%" align="center"> 205 <a accesskey="u" href="stl.html">Up</a> 206 </td> 207 <td width="40%" align="right">��<a accesskey="n" href="stl_primitive_rw.html">Next</a></td> 208 </tr> 209 <tr> 210 <td width="40%" align="left" valign="top">Using transactions in dbstl��</td> 211 <td width="20%" align="center"> 212 <a accesskey="h" href="index.html">Home</a> 213 </td> 214 <td width="40%" align="right" valign="top">��Working with primitive types </td> 215 </tr> 216 </table> 217 </div> 218 </body> 219</html> 220