#include <db_cxx.h>

int
DbEnv::set_thread_id(int (*thread_id)(DbEnv *dbenv, pid_t *pid, db_threadid_t *tid));

Description: DbEnv::set_thread_id

Declare a function that returns a unique identifier pair for the current thread of control. The DbEnv::set_thread_id method supports the DbEnv::failchk method. For more information, see Architecting Data Store and Concurrent Data Store applications, and Architecting Transactional Data Store applications.

The DbEnv::set_thread_id method configures operations performed using the specified DbEnv handle, not all operations performed on the underlying database environment.

The DbEnv::set_thread_id method may be called at any time during the life of the application.

The DbEnv::set_thread_id 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.

Parameters

thread_id

The thread_id 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:

dbenv

The dbenv parameter is the enclosing database environment handle, allowing application access to the application-private fields of that object.

pid

The pid points to a memory location of type pid_t. The process ID of the current thread of control may be returned in this memory location.

tid

The tid points to a memory location of type db_threadid_t. The thread ID of the current thread of control may be returned in this memory location.

The standard system library calls to return process and thread IDs are often sufficient for this purpose (for example, getpid() and pthread_self() 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 DbEnv::failchk method is run, it may be possible for DbEnv::failchk to not detect that a thread of control exited without properly releasing all Berkeley DB resources.

It may be possible to handle this problem by inhibiting process or thread creation between thread of control exit and calling DbEnv::failchk. Alternatively, the thread_id function must be constructed to not re-use pid/tid 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 is_alive function specified to the DbEnv::set_isalive method must be compatible with any thread_id function specified to DbEnv::set_thread_id.

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: Sleepycat Software does not currently know of any systems where this is necessary. If your application has to solve this problem, please contact our support group by email and let us know.

If no thread_id function is specified by the application, the Berkeley DB library will identify threads of control by using the taskIdSelf() call on VxWorks, the getpid() and GetCurrentThreadID() calls on Windows, the getpid() and pthread_self() calls when the Berkeley DB library has been configured for POSIX pthreads or Solaris LWP threads, the getpid() and thr_self() calls when the Berkeley DB library has been configured for UI threads, and otherwise getpid().

Errors

The DbEnv::set_thread_id method may fail and throw DbException, encapsulating one of the following non-zero errors, or return one of the following non-zero errors:

EINVAL

An invalid flag value or parameter was specified.

Class

See Also