NNAAMMEE db_thread - using threads in the DB library. DDEESSCCRRIIPPTTIIOONN 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 func- tions, 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 _d_b___i_n_t_r_o(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 _d_b___a_p_p_i_n_i_t(3) (or, in the C++ API, _D_b_E_n_v_:_:_a_p_p_i_n_i_t(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 avail- able in C language environments and which may not them- selves 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 _d_b___a_p_p_i_n_i_t (_D_b_E_n_v_:_:_a_p_p_i_n_i_t) 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 _d_b___o_p_e_n(3) (_D_b_:_:_o_p_e_n(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 _d_b___d_b_t(3) (_D_b_t(3)) for more information. +o The DB_CURRENT, DB_NEXT and DB_PREV flags to the _l_o_g___g_e_t (_D_b_L_o_g_:_:_g_e_t) 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 _l_o_g___o_p_e_n(3) (_D_b_L_o_g_:_:_o_p_e_n). See _d_b___l_o_g(3) (_D_b_L_o_g(3)) for more information. +o Each database operation (i.e., any call to a function underlying the handles returned by _d_b___o_p_e_n(3) and _d_b___c_u_r_s_o_r(3)) (_D_b(3) and _D_b_c(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 transac- tion 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 com- piler/architecture combination. Attempting to specify the DB_THREAD flag will fail if spinlocks are not avail- able. +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-applica- tion basis, see _d_b___j_u_m_p___s_e_t(3) for more information. CCOOMMPPIILLIINNGG TTHHRREEAADDEEDD AAPPPPLLIICCAATTIIOONNSS 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 SSEEEE AALLSSOO _d_b___a_r_c_h_i_v_e(1), _d_b___c_h_e_c_k_p_o_i_n_t(1), _d_b___d_e_a_d_l_o_c_k(1), _d_b___d_u_m_p(1), _d_b___l_o_a_d(1), _d_b___r_e_c_o_v_e_r(1), _d_b___s_t_a_t(1), _d_b___i_n_t_r_o(3), _d_b___a_p_p_i_n_i_t(3), _d_b___c_u_r_s_o_r(3), _d_b___d_b_m(3), _d_b___i_n_t_e_r_n_a_l(3), _d_b___l_o_c_k(3), _d_b___l_o_g(3), _d_b___m_p_o_o_l(3), _d_b___o_p_e_n(3), _d_b___t_h_r_e_a_d(3), _d_b___t_x_n(3)