DbEnv::set_thread_id()
Prev | Chapter 5. The DbEnv Handle | Next

## DbEnv::set_thread_id()

    #include <db_cxx.h>

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

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 , both in the Berkeley DB Programmer's Reference Guide.

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`, or NULL. The process ID of the current thread of control may be returned in this memory location, if it is not NULL.

- tid

  The tid points to a memory location of type `db_threadid_t`, or NULL. The thread ID of the current thread of control may be returned in this memory location, if it is not NULL.

### Errors

The `DbEnv::set_thread_id()` method may fail and throw a DbException exception, 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.

### Assigning Thread IDs

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 the DbEnv::failchk() method. 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: 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.

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()`.

### Class

DbEnv

### See Also

Database Environments and Related Methods

Prev | Up | Next
DbEnv::set_thread_count() | Home | DbEnv::set_thread_id_string()