m4_comment([$Id: mt.so,v 10.48 2005/07/20 16:34:05 bostic Exp $])m4_ref_title(Programmer Notes,    Multithreaded applications,    building @threaded applications,    program/environ, program/scope)m4_p([dnlm4_db fully supports multithreaded applications.  The m4_db library isnot itself multithreaded, and was deliberately architected to not usethreads internally because of the portability problems that wouldintroduce.  Database environment and database object handles returnedfrom m4_db library functions are free-threaded.  No other object handlesreturned from the m4_db library are free-threaded.  The following rulesshould be observed when using threads to access the m4_db library:])m4_nlistbeginm4_nlist([dnlThe m4_ref(DB_THREAD) flag must be specified to the m4_ref(dbenv_open)and m4_refT(dbh_open)s if the m4_db handles returned by those interfaceswill be used in the context of more than one thread.  Setting them4_ref(DB_THREAD) flag inconsistently may result in database corruption.m4_p([dnlThreading is assumed in the Java API, so no special flags are required;and m4_db functions will always behave as if the m4_ref(DB_THREAD) flagwas specified.])m4_p([dnlOnly a single thread may call the m4_ref(dbenv_close) or m4_refT(dbh_close)sfor a returned environment or database handle.])m4_p([dnlNo other m4_db handles are free-threaded.])])m4_nlist([dnlWhen using the non-cursor m4_db calls to retrieve key/data items (forexample, m4_ref(dbh_get)), the memory to which the pointer stored intothe Dbt refers is valid only until the next call using the m4_ref(Db)handle returned by m4_ref(dbh_open).  This includes m4_bold(any) use ofthe returned m4_ref(Db) handle, including by another thread within theprocess.m4_p([dnlFor this reason, if the m4_ref(DB_THREAD) handle was specified to them4_refT(dbh_open), either m4_ref(DB_DBT_MALLOC), m4_ref(DB_DBT_REALLOC),or m4_ref(DB_DBT_USERMEM) must be specified in the m4_ref(Dbt) whenperforming any non-cursor key or data retrieval.])])m4_nlist([dnlCursors may not span transactions.  Each cursor must beallocated and deallocated within the same transaction.m4_p([dnlTransactions and cursors may span threads, but only serially, that is,the application must serialize access to the m4_ref(DbTxn) andm4_ref(Dbc) handles.  In the case of nested transactions, since allchild transactions are part of the same parent transaction, they must observethe same constraints.  That is, children may execute in different threadsonly if each child executes serially.])])m4_nlist([dnlUser-level synchronization mutexes must have been implemented for thecompiler/architecture combination.  Attempting to specify the DB_THREADflag will fail if fast mutexes are not available.m4_p([dnlIf blocking mutexes are available (for example POSIX pthreads), theywill be used.  Otherwise, the m4_db library will make a system call topause for some amount of time when it is necessary to wait on a lock.This may not be optimal, especially in a thread-only environment, inwhich it is usually more efficient to explicitly yield the processor toanother thread.])m4_p([dnlIt is possible to specify a yield function on an per-application basis.See m4_ref(dbenv_set_func_yield) for more information.])m4_p([dnlIt is possible to specify the number of attempts that will be made toacquire the mutex before waiting.  See m4_ref(mutex_set_tas_spins) formore information.])])m4_nlistendm4_p([dnlWhen creating multiple databases in a single physical file, multithreadedprograms may have additional requirements.  For more information, seem4_link(M4RELDIR/ref/am/opensub, [Opening multiple databases in a singlefile].)])m4_page_footer