<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>DbEnv::set_thread_id()</title>
<link rel="stylesheet" href="apiReference.css" type="text/css" />
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
<link rel="start" href="index.html" title="Berkeley DB C++ API Reference" />
<link rel="up" href="env.html" title="Chapter 5. The DbEnv Handle" />
<link rel="prev" href="envset_thread_count.html" title="DbEnv::set_thread_count()" />
<link rel="next" href="envset_thread_id_string.html" title="DbEnv::set_thread_id_string()" />
</head>
<body>
<div class="navheader">
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">DbEnv::set_thread_id()</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="envset_thread_count.html">Prev</a> </td>
<th width="60%" align="center">Chapter 5.
The DbEnv Handle
</th>
<td width="20%" align="right"> <a accesskey="n" href="envset_thread_id_string.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="envset_thread_id"></a>DbEnv::set_thread_id()</h2>
</div>
</div>
</div>
<pre class="programlisting">#include <db_cxx.h>
int
DbEnv::set_thread_id(void (*thread_id)(DbEnv *dbenv,
pid_t *pid, db_threadid_t *tid));</pre>
<p>
Declare a function that returns a unique identifier pair for the
current thread of control. The
<code class="methodname">DbEnv::set_thread_id()</code> method supports the
<a class="xref" href="envfailchk.html" title="DbEnv::failchk()">DbEnv::failchk()</a> method.
For more information, see
<a href="../../programmer_reference/cam_app.html" class="olink">
Architecting Data Store and Concurrent Data Store applications
</a>, and
<a href="../../programmer_reference/transapp_app.html" class="olink">
Architecting Transactional Data Store applications
</a>, both in the
<em class="citetitle">Berkeley DB Programmer's Reference Guide</em>.
</p>
<p>
The <code class="methodname">DbEnv::set_thread_id()</code> method
configures operations performed using the specified
<a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a> handle, not all operations
performed on the underlying database environment.
</p>
<p>
The <code class="methodname">DbEnv::set_thread_id()</code> method may be
called at any time during the life of the application.
</p>
<p>
The <code class="methodname">DbEnv::set_thread_id()</code> <span>
<span>
method either returns a non-zero error value or throws an
exception that encapsulates a non-zero error value on
failure, and returns 0 on success.
</span>
</span>
</p>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="id3507598"></a>Parameters</h3>
</div>
</div>
</div>
<div class="sect3" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id3507608"></a>thread_id</h4>
</div>
</div>
</div>
<p>
The <span class="bold"><strong>thread_id</strong></span> parameter is a function
which returns a unique identifier pair for a thread of control in a
Berkeley DB application. The function takes three arguments:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
<span class="bold"><strong>dbenv</strong></span>
</p>
<p>
The <span class="bold"><strong>dbenv</strong></span> parameter is the enclosing
database environment handle, allowing application access to the
application-private fields of that object.
</p>
</li>
<li>
<p>
<span class="bold"><strong>pid</strong></span>
</p>
<p>
The <span class="bold"><strong>pid</strong></span> points to a memory location of
type <code class="literal">pid_t</code>, or NULL. The process ID of the current
thread of control may be returned in this memory location, if it is not
NULL.
</p>
</li>
<li>
<p>
<span class="bold"><strong>tid</strong></span>
</p>
<p>
The <span class="bold"><strong>tid</strong></span> points to a memory location of
type <code class="literal">db_threadid_t</code>, or NULL. The thread ID of the
current thread of control may be returned in this memory location, if it
is not NULL.
</p>
</li>
</ul>
</div>
</div>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="id3507760"></a>Errors</h3>
</div>
</div>
</div>
<p>
The <code class="methodname">DbEnv::set_thread_id()</code> <span>
<span>
method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a>
exception, encapsulating one of the following non-zero errors, or return one
of the following non-zero errors:
</span>
</span>
</p>
<div class="sect3" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h4 class="title"><a id="id3507906"></a>EINVAL</h4>
</div>
</div>
</div>
<p>
An invalid flag value or parameter was specified.
</p>
</div>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="id3507860"></a>Assigning Thread IDs</h3>
</div>
</div>
</div>
<p>
The standard system library calls to return process and thread IDs are often sufficient for this
purpose (for example, <code class="methodname">getpid()</code> and
<code class="methodname">pthread_self()</code> on POSIX systems or GetCurrentThreadID on Windows
systems). However, if the Berkeley DB application dynamically creates processes or threads, some
care may be necessary in assigning unique IDs. In most threading systems, process and thread IDs are
available for re-use as soon as the process or thread exits. If a new process or thread is created
between the time of process or thread exit, and the
<a class="xref" href="envfailchk.html" title="DbEnv::failchk()">DbEnv::failchk()</a> method is run, it may be possible for
<a class="xref" href="envfailchk.html" title="DbEnv::failchk()">DbEnv::failchk()</a>
to not detect that a thread of control exited without properly
releasing all Berkeley DB resources.
</p>
<p>
It may be possible to handle this problem by inhibiting process or thread
creation between thread of control exit and calling the
<a class="xref" href="envfailchk.html" title="DbEnv::failchk()">DbEnv::failchk()</a>
method. Alternatively, the <span class="bold"><strong>thread_id</strong></span> function
must be constructed to not re-use <span class="bold"><strong>pid/tid</strong></span>
pairs. For example, in a single process application, the returned process ID
might be used as an incremental counter, with the returned thread ID set to the
actual thread ID. Obviously, the <span class="bold"><strong>is_alive</strong></span>
function specified to the
<a class="xref" href="envset_isalive.html" title="DbEnv::set_isalive()">DbEnv::set_isalive()</a>
method must be compatible with any
<span class="bold"><strong>thread_id</strong></span> function specified to
<code class="methodname">DbEnv::set_thread_id()</code>.
</p>
<p>
The db_threadid_t type is configured to be the same type as a standard thread identifier, in
Berkeley DB configurations where this type is known (for example, systems supporting pthread_t or
thread_t, or DWORD on Windows). If the Berkeley DB configuration process is unable to determine the
type of a standard thread identifier, the db_thread_t type is set to uintmax_t (or the largest
available unsigned integral type, on systems lacking the uintmax_t type). Applications running on
systems lacking a detectable standard thread type, and which are also using thread APIs where a
thread identifier is not an integral value and so will not fit into the configured db_threadid_t
type, must either translate between the db_threadid_t type and the thread identifier (mapping the
thread identifier to a unique identifier of the appropriate size), or modify the Berkeley DB sources
to use an appropriate db_threadid_t type. Note: we do not currently know of any systems where this
is necessary. If your application has to solve this problem, please contact our support group and
let us know.
</p>
<p>
If no <span class="bold"><strong>thread_id</strong></span> function is specified by the
application, the Berkeley DB library will identify threads of control by using
the <code class="methodname">taskIdSelf()</code> call on VxWorks, the
<code class="methodname">getpid()</code> and
<code class="methodname">GetCurrentThreadID()</code> calls on Windows, the
<code class="methodname">getpid()</code> and <code class="methodname">pthread_self()</code>
calls when the Berkeley DB library has been configured for POSIX pthreads or
Solaris LWP threads, the <code class="methodname">getpid()</code> and
<code class="methodname">thr_self()</code> calls when the Berkeley DB library has been
configured for UI threads, and otherwise <code class="methodname">getpid()</code>.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="id3507731"></a>Class</h3>
</div>
</div>
</div>
<p>
<a class="link" href="env.html" title="Chapter 5. The DbEnv Handle">DbEnv</a>
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="id3507601"></a>See Also</h3>
</div>
</div>
</div>
<p>
<a class="xref" href="env.html#envlist" title="Database Environments and Related Methods">Database Environments and Related Methods</a>
</p>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="envset_thread_count.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="env.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="envset_thread_id_string.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">DbEnv::set_thread_count() </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> DbEnv::set_thread_id_string()</td>
</tr>
</table>
</div>
</body>
</html>
