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