1<!--$Id: env_set_thread_id.so,v 10.9 2006/08/24 16:32:23 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB: DB_ENV->set_thread_id</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td> 13<b>DB_ENV->set_thread_id</b> 14</td> 15<td align=right> 16<a href="../api_c/api_core.html"><img src="../images/api.gif" alt="API"></a> 17<a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a></td> 18</tr></table> 19<hr size=1 noshade> 20<tt> 21<b><pre> 22#include <db.h> 23<p> 24int 25DB_ENV->set_thread_id(DB_ENV *dbenv, 26 void (*thread_id)(DB_ENV *dbenv, pid_t *pid, db_threadid_t *tid)); 27</pre></b> 28<hr size=1 noshade> 29<b>Description: DB_ENV->set_thread_id</b> 30<p>Declare a function that returns a unique identifier pair for the current 31thread of control. The DB_ENV->set_thread_id method supports the 32<a href="../api_c/env_failchk.html">DB_ENV->failchk</a> method. For more information, see 33<a href="../ref/cam/app.html">Architecting Data Store and Concurrent 34Data Store applications</a>, and <a href="../ref/transapp/app.html">Architecting Transactional Data Store applications</a>.</p> 35<p>The DB_ENV->set_thread_id method configures operations performed using the specified 36<a href="../api_c/env_class.html">DB_ENV</a> handle, not all operations performed on the underlying 37database environment.</p> 38<p>The DB_ENV->set_thread_id method may be called at any time during the life of the 39application.</p> 40<p>The DB_ENV->set_thread_id method 41returns a non-zero error value on failure 42and 0 on success. 43</p> 44<b>Parameters</b> <br> 45 <b>thread_id</b><ul compact><li>The <b>thread_id</b> parameter is a function which returns a unique 46identifier pair for a thread of control in a Berkeley DB application. The 47function takes three arguments:</ul> 48<br> 49<b><b>dbenv</b></b><ul compact><li>The <b>dbenv</b> parameter is the enclosing database environment 50handle, allowing application access to the application-private fields 51of that object.</ul> 52<b><b>pid</b></b><ul compact><li>The <b>pid</b> points to a memory location of type pid_t. The 53process ID of the current thread of control may be returned in 54this memory location.</ul> 55<b><b>tid</b></b><ul compact><li>The <b>tid</b> points to a memory location of type db_threadid_t. The 56thread ID of the current thread of control may be returned in this 57memory location.</ul> 58<br> 59<br> 60<p>The standard system library calls to return process and thread IDs are 61often sufficient for this purpose (for example, getpid() and 62pthread_self() on POSIX systems or GetCurrentThreadID on Windows 63systems). However, if the Berkeley DB application dynamically creates 64processes or threads, some care may be necessary in assigning unique 65IDs. In most threading systems, process and thread IDs are available 66for re-use as soon as the process or thread exits. If a new process or 67thread is created between the time of process or thread exit, and the 68<a href="../api_c/env_failchk.html">DB_ENV->failchk</a> method is run, it may be possible for 69<a href="../api_c/env_failchk.html">DB_ENV->failchk</a> to not detect that a thread of control exited 70without properly releasing all Berkeley DB resources.</p> 71<p>It may be possible to handle this problem by inhibiting process or 72thread creation between thread of control exit and calling 73<a href="../api_c/env_failchk.html">DB_ENV->failchk</a>. Alternatively, the <b>thread_id</b> function 74must be constructed to not re-use <b>pid</b>/<b>tid</b> pairs. For 75example, in a single process application, the returned process ID might 76be used as an incremental counter, with the returned thread ID set to 77the actual thread ID. Obviously, the <b>is_alive</b> function 78specified to the <a href="../api_c/env_set_isalive.html">DB_ENV->set_isalive</a> method must be compatible with any 79<b>thread_id</b> function specified to DB_ENV->set_thread_id.</p> 80<p>The db_threadid_t type is configured to be the same type as a standard 81thread identifier, in Berkeley DB configurations where this type is known (for 82example, systems supporting pthread_t or thread_t, or DWORD on Windows). 83If the Berkeley DB configuration process is unable to determine the type of a 84standard thread identifier, the db_thread_t type is set to uintmax_t (or 85the largest available unsigned integral type, on systems lacking the 86uintmax_t type). Applications running on systems lacking a detectable 87standard thread type, and which are also using thread APIs where a 88thread identifier is not an integral value and so will not fit into the 89configured db_threadid_t type, must either translate between the 90db_threadid_t type and the thread identifier (mapping the thread 91identifier to a unique identifier of the appropriate size), or modify 92the Berkeley DB sources to use an appropriate db_threadid_t type. Note: we 93do not currently know of any systems where this is necessary. If your 94application has to solve this problem, please contact our support group 95and let us know.</p> 96<p>If no <b>thread_id</b> function is specified by the application, the 97Berkeley DB library will identify threads of control by using the taskIdSelf() 98call on VxWorks, the getpid() and GetCurrentThreadID() calls on Windows, 99the getpid() and pthread_self() calls when the Berkeley DB library has been 100configured for POSIX pthreads or Solaris LWP threads, the getpid() and 101thr_self() calls when the Berkeley DB library has been configured for UI 102threads, and otherwise getpid().</p> 103<br><b>Errors</b> 104<p>The DB_ENV->set_thread_id method 105may fail and return one of the following non-zero errors:</p> 106<br> 107<b>EINVAL</b><ul compact><li>An 108invalid flag value or parameter was specified.</ul> 109<br> 110<hr size=1 noshade> 111<br><b>Class</b> 112<a href="../api_c/env_class.html">DB_ENV</a> 113<br><b>See Also</b> 114<a href="../api_c/env_list.html">Database Environments and Related Methods</a> 115</tt> 116<table width="100%"><tr><td><br></td><td align=right> 117<a href="../api_c/api_core.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a> 118</td></tr></table> 119<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 120</body> 121</html> 122
