mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-16 17:16:25 +00:00
274 lines
13 KiB
HTML
274 lines
13 KiB
HTML
<?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>DB_ENV->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 DB_ENV Handle" />
|
||
<link rel="prev" href="envset_thread_count.html" title="DB_ENV->set_thread_count()" />
|
||
<link rel="next" href="envset_thread_id_string.html" title="DB_ENV->set_thread_id_string()" />
|
||
</head>
|
||
<body>
|
||
<div xmlns="" class="navheader">
|
||
<div class="libver">
|
||
<p>Library Version 11.2.5.3</p>
|
||
</div>
|
||
<table width="100%" summary="Navigation header">
|
||
<tr>
|
||
<th colspan="3" align="center">DB_ENV->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 DB_ENV 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>DB_ENV->set_thread_id()</h2>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<pre class="programlisting">#include <db.h>
|
||
|
||
int
|
||
DB_ENV->set_thread_id(DB_ENV *dbenv,
|
||
void (*thread_id)(DB_ENV *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">DB_ENV->set_thread_id()</code> method supports the
|
||
<a class="xref" href="envfailchk.html" title="DB_ENV->failchk()">DB_ENV->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">DB_ENV->set_thread_id()</code> method
|
||
configures operations performed using the specified
|
||
<a class="link" href="env.html" title="Chapter 5. The DB_ENV Handle">DB_ENV</a> handle, not all operations
|
||
performed on the underlying database environment.
|
||
</p>
|
||
<p>
|
||
The <code class="methodname">DB_ENV->set_thread_id()</code> method may be
|
||
called at any time during the life of the application.
|
||
</p>
|
||
<p>
|
||
The <code class="methodname">DB_ENV->set_thread_id()</code> <span>
|
||
<span>
|
||
method returns a non-zero error value on failure and 0 on success.
|
||
</span>
|
||
|
||
</span>
|
||
</p>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="idp60203984"></a>Parameters</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sect3" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h4 class="title"><a id="idp60219520"></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="idp60230224"></a>Errors</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
The <code class="methodname">DB_ENV->set_thread_id()</code> <span>
|
||
<span>
|
||
method may fail and 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="idp60235328"></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="idp60234120"></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="DB_ENV->failchk()">DB_ENV->failchk()</a> method is run, it may be possible for
|
||
<a class="xref" href="envfailchk.html" title="DB_ENV->failchk()">DB_ENV->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="DB_ENV->failchk()">DB_ENV->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="DB_ENV->set_isalive()">DB_ENV->set_isalive()</a>
|
||
method must be compatible with any
|
||
<span class="bold"><strong>thread_id</strong></span> function specified to
|
||
<code class="methodname">DB_ENV->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="idp60232024"></a>Class</h3>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>
|
||
<a class="link" href="env.html" title="Chapter 5. The DB_ENV Handle">DB_ENV</a>
|
||
</p>
|
||
</div>
|
||
<div class="sect2" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h3 class="title"><a id="idp60238008"></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">DB_ENV->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"> DB_ENV->set_thread_id_string()</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html>
|