db_thread


       The  DB  library  is  a family of groups of functions that
       provides a modular programming interface  to  transactions
       and  record-oriented  file  access.   The library includes
       support for transactions, locking, logging and  file  page
       caching,  as well as various indexed access methods.  Many
       of the functional groups  (e.g.,  the  file  page  caching
       functions)   are   useful  independent  of  the  other  DB
       functions, although some functional groups are  explicitly
       based  on  other functional groups (e.g., transactions and
       logging).  For a general description of  the  DB  package,
       see db_intro(3).

       This  manual pages describes the specific details of using
       DB from within threaded programs.

       The DB library is not itself multi-threaded.  The  library
       was deliberately architected to not use threads internally
       because of the portability  problems  that  using  threads
       within   the  library  would  introduce.   Object  handles
       returned from  DB  library  functions  are  free-threaded,
       i.e.,  threads may use handles concurrently, by specifying
       the DB_THREAD flag to db_appinit(3) (or, in the  C++  API,
       DbEnv::appinit(3)) and the other subsystem open functions.
       Threading is assumed in the Java API, so no special  flags
       are  required,  and  DB functions will always behave as if
       the DB_THREAD flag was specified.

       DB supports multi-threaded applications  with  the  caveat
       that  it  loads  and  calls  functions  that  are commonly
       available in C language environments  and  which  may  not
       themselves  be thread-safe.  Other than this usage, DB has
       no static data and  maintains  no  local  context  between
       calls  to  DB  functions.  To ensure that applications can
       safely use threads in the context of DB,  porters  to  new
       operating systems and/or C libraries must confirm that the
       system and C library functions used by the DB library  are
       thread-safe.

       There  are  some additional caveats about using threads to
       access the DB library:

       o The DB_THREAD flag must be specified for all  subsystems
         either explicitly or via the db_appinit (DbEnv::appinit)
         function in the C and C++ APIs.  Threading is assumed in
         the  Java  API, so no special flags are required, and DB
         functions will always behave as if  the  DB_THREAD  flag
         was specified.

         Setting  the DB_THREAD flag inconsistently may result in
         database corruption.

       o Only a single thread may call the close function  for  a
         returned  database  or subsystem handle.  See db_open(3)
         (Db::open(3)) and the appropriate subsystem manual pages
         for more information.

       o Either the DB_DBT_MALLOC or DB_DBT_USERMEM flags must be
         set in a DBT  used  for  key  or  data  retrieval.   See
         db_dbt(3) (Dbt(3)) for more information.

       o The DB_CURRENT, DB_NEXT and DB_PREV flags to the log_get
         (DbLog::get) function may not be used by a free-threaded
         handle.   If  such  calls are necessary, a thread should
         explicitly create a  unique  DB_LOG  handle  by  calling
         log_open(3) (DbLog::open).  See db_log(3) (DbLog(3)) for
         more information.

       o Each database operation (i.e., any call  to  a  function
         underlying   the  handles  returned  by  db_open(3)  and
         db_cursor(3)) (Db(3) and Dbc(3)) is  normally  performed
         on  behalf  of  a  unique  locker.   If, within a single
         thread of control, multiple calls on behalf of the  same
         locker are desired, then transactions must be used.  For
         example, consider the case where a cursor scan locates a
         record,  and  then  based  on that record, accesses some
         other item in the database.  If these are done using the
         default  lockers  for  the handle, there is no guarantee
         that these two operations will  not  conflict.   If  the
         application  wishes  to guarantee that the operations do
         not conflict, locks must be  obtained  on  behalf  of  a
         transaction,  instead  of  the  default locker id, and a
         transaction must be specified to the cursor creation and
         the subsequent db call.

       o Transactions   may   not   span   threads,   i.e.,  each
         transaction must begin and end in the same  thread,  and
         each transaction may only be used by a single thread.

       o Spinlocks   must   have   been   implemented   for   the
         compiler/architecture   combination.    Attempting    to
         specify  the  DB_THREAD  flag will fail if spinlocks are
         not available.

       o The DB library makes a system call  to  pause  for  some
         number of microseconds when it is necessary to wait on a
         lock.  This may not be optimal, especially in a  thread-
         only  environment  where  it  will  be more efficient to
         explicitly yield the processor to another thread.  It is
         possible   to  specify  a  yield  function  on  an  per-
         application   basis,   see   db_jump_set(3)   for   more
         information.

COMPILING THREADED APPLICATIONS

       Special  compile-time  flags  are  required when compiling
       threaded applications with the UNIX include files on  some
       architectures.

       On  IRIX, if you are compiling a threaded application, you
       must compile with the -D_SGI_MP_SOURCE flag:

            cc -D_SGI_MP_SOURCE ...

       On OSF/1, if you are compiling a threaded application, you
       must compile with the -D_REENTRANT flag:

            cc -D_REENTRANT ...

       On  Solaris,  if you are compiling a threaded application,
       you must compile with the -D_REENTRANT flag and link  with
       the -lthread library:

            cc -D_REENTRANT ... -lthread

db_thread

COMPILING THREADED APPLICATIONS

SEE ALSO