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>DbEnv::set_thread_id()</title> 7 <link rel="stylesheet" href="apiReference.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 C++ API Reference" /> 10 <link rel="up" href="env.html" title="Chapter 5. The DbEnv Handle" /> 11 <link rel="prev" href="envset_thread_count.html" title="DbEnv::set_thread_count()" /> 12 <link rel="next" href="envset_thread_id_string.html" title="DbEnv::set_thread_id_string()" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">DbEnv::set_thread_id()</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="envset_thread_count.html">Prev</a> </td> 22 <th width="60%" align="center">Chapter 5. 23 The DbEnv Handle 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="envset_thread_id_string.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="envset_thread_id"></a>DbEnv::set_thread_id()</h2> 35 </div> 36 </div> 37 </div> 38 <pre class="programlisting">#include <db_cxx.h> 39 40int 41DbEnv::set_thread_id(char *(*thread_id_string)(DbEnv *dbenv, 42 pid_t pid, db_threadid_t tid, char *buf));</pre> 43 <p> 44 Declare a function that returns a unique identifier pair for the 45 current thread of control. The <code class="methodname">DbEnv::set_thread_id()</code> method 46 supports the <a class="xref" href="envfailchk.html" title="DbEnv::failchk()">DbEnv::failchk()</a> method. 47 For more information, see 48 <a href="../../programmer_reference/cam_app.html" class="olink">Architecting Data Store and 49 Concurrent Data Store applications</a>, and 50 <a href="../../programmer_reference/transapp_app.html" class="olink">Architecting Transactional Data Store 51 applications</a>, both in the 52 <em class="citetitle">Berkeley DB Programmer's Reference Guide</em>. 53 </p> 54 <p> 55 The <code class="methodname">DbEnv::set_thread_id()</code> method configures operations performed 56 using the specified <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a> handle, not all 57 operations performed on the underlying database environment. 58 </p> 59 <p> 60 The <code class="methodname">DbEnv::set_thread_id()</code> method may be called at any time during 61 the life of the application. 62 </p> 63 <p> 64 The <code class="methodname">DbEnv::set_thread_id()</code> <span> 65 66 <span> 67 method either returns a non-zero error value or throws an 68 exception that encapsulates a non-zero error value on 69 failure, and returns 0 on success. 70 </span> 71 </span> 72 </p> 73 <div class="sect2" lang="en" xml:lang="en"> 74 <div class="titlepage"> 75 <div> 76 <div> 77 <h3 class="title"><a id="id1674976"></a>Parameters</h3> 78 </div> 79 </div> 80 </div> 81 <div class="sect3" lang="en" xml:lang="en"> 82 <div class="titlepage"> 83 <div> 84 <div> 85 <h4 class="title"><a id="id1674971"></a>thread_id</h4> 86 </div> 87 </div> 88 </div> 89 <p> 90 The <span class="bold"><strong>thread_id</strong></span> parameter is a function 91 which returns a unique identifier pair for a thread of control in a 92 Berkeley DB application. The function takes three arguments: 93 </p> 94 <div class="itemizedlist"> 95 <ul type="disc"> 96 <li> 97 <p> 98 <span class="bold"><strong>dbenv</strong></span> 99 </p> 100 <p> 101 The <span class="bold"><strong>dbenv</strong></span> parameter is the enclosing 102 database environment handle, allowing application access to the 103 application-private fields of that object. 104 </p> 105 </li> 106 <li> 107 <p> 108 <span class="bold"><strong>pid</strong></span> 109 </p> 110 <p> 111 The <span class="bold"><strong>pid</strong></span> points to a memory location of 112 type <code class="literal">pid_t</code>, or NULL. The process ID of the current 113 thread of control may be returned in this memory location, if it is not 114 NULL. 115 </p> 116 </li> 117 <li> 118 <p> 119 <span class="bold"><strong>tid</strong></span> 120 </p> 121 <p> 122 The <span class="bold"><strong>tid</strong></span> points to a memory location of 123 type <code class="literal">db_threadid_t</code>, or NULL. The thread ID of the 124 current thread of control may be returned in this memory location, if it 125 is not NULL. 126 </p> 127 </li> 128 </ul> 129 </div> 130 </div> 131 </div> 132 <div class="sect2" lang="en" xml:lang="en"> 133 <div class="titlepage"> 134 <div> 135 <div> 136 <h3 class="title"><a id="id1675167"></a>Errors</h3> 137 </div> 138 </div> 139 </div> 140 <p> 141 The <code class="methodname">DbEnv::set_thread_id()</code> <span> 142 143 <span> 144 method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 145 exception, encapsulating one of the following non-zero errors, or return one 146 of the following non-zero errors: 147 </span> 148 </span> 149 </p> 150 <div class="sect3" lang="en" xml:lang="en"> 151 <div class="titlepage"> 152 <div> 153 <div> 154 <h4 class="title"><a id="id1675331"></a>EINVAL</h4> 155 </div> 156 </div> 157 </div> 158 <p> 159 An invalid flag value or parameter was specified. 160 </p> 161 </div> 162 </div> 163 <div class="sect2" lang="en" xml:lang="en"> 164 <div class="titlepage"> 165 <div> 166 <div> 167 <h3 class="title"><a id="id1675337"></a>Assigning Thread IDs</h3> 168 </div> 169 </div> 170 </div> 171 <p> 172 The standard system library calls to return process and thread IDs are often sufficient for this 173 purpose (for example, <code class="methodname">getpid()</code> and 174 <code class="methodname">pthread_self()</code> on POSIX systems or GetCurrentThreadID on Windows 175 systems). However, if the Berkeley DB application dynamically creates processes or threads, some 176 care may be necessary in assigning unique IDs. In most threading systems, process and thread IDs are 177 available for re-use as soon as the process or thread exits. If a new process or thread is created 178 between the time of process or thread exit, and the 179 <a class="xref" href="envfailchk.html" title="DbEnv::failchk()">DbEnv::failchk()</a> method is run, it may be possible for 180 <a class="xref" href="envfailchk.html" title="DbEnv::failchk()">DbEnv::failchk()</a> 181 to not detect that a thread of control exited without properly 182 releasing all Berkeley DB resources. 183 </p> 184 <p> 185 It may be possible to handle this problem by inhibiting process or thread 186 creation between thread of control exit and calling the 187 <a class="xref" href="envfailchk.html" title="DbEnv::failchk()">DbEnv::failchk()</a> 188 method. Alternatively, the <span class="bold"><strong>thread_id</strong></span> function 189 must be constructed to not re-use <span class="bold"><strong>pid/tid</strong></span> 190 pairs. For example, in a single process application, the returned process ID 191 might be used as an incremental counter, with the returned thread ID set to the 192 actual thread ID. Obviously, the <span class="bold"><strong>is_alive</strong></span> 193 function specified to the 194 <a class="xref" href="envset_isalive.html" title="DbEnv::set_isalive()">DbEnv::set_isalive()</a> 195 method must be compatible with any 196 <span class="bold"><strong>thread_id</strong></span> function specified to 197 <code class="methodname">DbEnv::set_thread_id()</code>. 198 </p> 199 <p> 200 The db_threadid_t type is configured to be the same type as a standard thread identifier, in 201 Berkeley DB configurations where this type is known (for example, systems supporting pthread_t or 202 thread_t, or DWORD on Windows). If the Berkeley DB configuration process is unable to determine the 203 type of a standard thread identifier, the db_thread_t type is set to uintmax_t (or the largest 204 available unsigned integral type, on systems lacking the uintmax_t type). Applications running on 205 systems lacking a detectable standard thread type, and which are also using thread APIs where a 206 thread identifier is not an integral value and so will not fit into the configured db_threadid_t 207 type, must either translate between the db_threadid_t type and the thread identifier (mapping the 208 thread identifier to a unique identifier of the appropriate size), or modify the Berkeley DB sources 209 to use an appropriate db_threadid_t type. Note: we do not currently know of any systems where this 210 is necessary. If your application has to solve this problem, please contact our support group and 211 let us know. 212 </p> 213 <p> 214 If no <span class="bold"><strong>thread_id</strong></span> function is specified by the 215 application, the Berkeley DB library will identify threads of control by using 216 the <code class="methodname">taskIdSelf()</code> call on VxWorks, the 217 <code class="methodname">getpid()</code> and 218 <code class="methodname">GetCurrentThreadID()</code> calls on Windows, the 219 <code class="methodname">getpid()</code> and <code class="methodname">pthread_self()</code> 220 calls when the Berkeley DB library has been configured for POSIX pthreads or 221 Solaris LWP threads, the <code class="methodname">getpid()</code> and 222 <code class="methodname">thr_self()</code> calls when the Berkeley DB library has been 223 configured for UI threads, and otherwise <code class="methodname">getpid()</code>. 224 </p> 225 </div> 226 <div class="sect2" lang="en" xml:lang="en"> 227 <div class="titlepage"> 228 <div> 229 <div> 230 <h3 class="title"><a id="id1675073"></a>Class</h3> 231 </div> 232 </div> 233 </div> 234 <p> 235 <a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a> 236 </p> 237 </div> 238 <div class="sect2" lang="en" xml:lang="en"> 239 <div class="titlepage"> 240 <div> 241 <div> 242 <h3 class="title"><a id="id1675187"></a>See Also</h3> 243 </div> 244 </div> 245 </div> 246 <p> 247 <a class="xref" href="env.html#envlist" title="Database Environments and Related Methods">Database Environments and Related Methods</a> 248 </p> 249 </div> 250 </div> 251 <div class="navfooter"> 252 <hr /> 253 <table width="100%" summary="Navigation footer"> 254 <tr> 255 <td width="40%" align="left"><a accesskey="p" href="envset_thread_count.html">Prev</a> </td> 256 <td width="20%" align="center"> 257 <a accesskey="u" href="env.html">Up</a> 258 </td> 259 <td width="40%" align="right"> <a accesskey="n" href="envset_thread_id_string.html">Next</a></td> 260 </tr> 261 <tr> 262 <td width="40%" align="left" valign="top">DbEnv::set_thread_count() </td> 263 <td width="20%" align="center"> 264 <a accesskey="h" href="index.html">Home</a> 265 </td> 266 <td width="40%" align="right" valign="top"> DbEnv::set_thread_id_string()</td> 267 </tr> 268 </table> 269 </div> 270 </body> 271</html> 272