-I<Berkeley DB Reference Guide: Programmer Notes[P6

Berkeley DB Reference Guide: Programmer Notes



:

Building multi-threaded applications



5The Berkeley DB library is not itself multi-threaded.FThe library was deliberately architected to not use threads internallyIbecause of the portability problems that using threads within the librarywould introduce.MObject handles returned from Berkeley DB library functions are free-threaded,Gi.e., threads may use handles concurrently, by specifying the DB_THREADgflag to db_appinit and the other subsystem open functions.GThreading is assumed in the Java API, so no special flags are required,Tand Berkeley DB functions will always behave as if the DB_THREAD flag was specified.

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

?There are some additional caveats about using threads to accessthe Berkeley DB library:

    P

  1. The DB_THREAD flag must be specified for all subsystems either explicitlynor via the db_appinit function. Threading is assumed in the JavaLAPI, so no special flags are required, and Berkeley DB functions will always.behave as if the DB_THREAD flag was specified.

    LSetting the DB_THREAD flag inconsistently may result in database corruption.i

  2. Only a single thread may call the DB->close function for a&returned database or subsystem handle.T

  3. When using the non-cursor Berkeley DB calls to retrieve key/data items (e.g.,hDB->get), the memory referenced by the pointer stored into the Dbt9is only valid until the next call to using the DB handlebreturned by db_open. (This includes any use of the returned<DB handle, including by another thread of control within theFprocess. For this reason, when multiple threads are using the returnedhDB handle concurrently, either the DB_DBT_MALLOC ornDB_DBT_USERMEM flag must be specified for any non-cursorFDBT used for key or data retrieval.) When using the cursor Berkeley DB<calls to retrieve key/data items (e.g., dbc_get), the memory>referenced by the pointer into the DBT is only valid until the9next call to Berkeley DB using the DBC handle returned by4DB->cursor.q

  4. The DB_CURRENT, DB_NEXT and DB_PREV flags to the log_get functionHmay not be used by a free-threaded handle. If such calls are necessary,Ca thread should explicitly create a unique DB_LOG handle by calling3log_open.K

  5. Each database operation (i.e., any call to a function underlying the†handles returned by db_open and DB->cursor is normallyFperformed on behalf of a unique locker. If, within a single thread ofFcontrol, multiple calls on behalf of the same locker are desired, thenItransactions must be used. For example, consider the case where a cursorIscan locates a record, and then based on that record, accesses some otherFitem in the database. If these are done using the default lockers forDthe handle, there is no guarantee that these two operations will notHconflict. If the application wishes to guarantee that the operations doHnot conflict, locks must be obtained on behalf of a transaction, insteadDof the default locker id, and a transaction must be specified to theKcursor creation and the subsequentBerkeley DB calls.O

  6. Transactions may not span threads, i.e., each transaction must begin andIend in the same thread, and each transaction may only be used by a singlethread.I

  7. Spinlocks must have been implemented for the compiler/architectureCcombination. Attempting to specify the DB_THREAD flag will fail ifspinlocks are not available.N

  8. The Berkeley DB library makes a system call to pause for some number ofEmicroseconds when it is necessary to wait on a lock. This may not beFoptimal, especially in a thread-only environment where it will be moreEefficient to explicitly yield the processor to another thread. It ispossible to specify aByield functionon an per-application basis.
(

Compiling Threaded Applications

LSpecial compile-time flags are required when compiling threaded applications2with the UNIX include files on some architectures.

AOn FreeBSD, if you are compiling a threaded application, you must=compile with the _THREAD_SAFE flag and link with the libc_r.alibrary:

5



5On IRIX, if you are compiling a threaded application,.you must compile with the _SGI_MP_SOURCE flag:

1



6On OSF/1, if you are compiling a threaded application,*you must compile with the _REENTRANT flag:

-



IOn Solaris, if you are compiling a threaded application, you must compile?with the _REENTRANT flag and link with the libthread.a library:

6



OAKÿÿ