Berkeley DB Reference Guide: Programmer Notes

Berkeley DB handles

The Berkeley DB library has a number of object handles. The following table lists those handles, their scope, and if they are free-threaded, that is, if multiple threads within a process can share them.

DB_ENV

The DB_ENV handle is created by the db_env_create function and references a Berkeley DB database environment, a collection of databases and Berkeley DB subsystems. DB_ENV handles are free-threaded if the DB_THREAD flag is specified to the DBENV->open function when the environment is opened. The handle should not be closed while any other handle remains open that is using it as a reference (e.g., DB or DB_TXN). Once either the DBENV->close or DBENV->remove functions are called, the handle may not be accessed again, regardless of the function's return.

DB_TXN

The DB_TXN handle is created by the txn_begin function and references a single transaction. The handle is not free-threaded, and transactions may not span threads nor may transactions be used by more than a single thread. Once the txn_abort or txn_commit functions are called, the handle may not be accessed again, regardless of the function's return. In addition, parent transactions may not issue any Berkeley DB operations, except for txn_begin, txn_abort and txn_commit, while it has active child transactions (child transactions that have not yet been committed or aborted).

DB_MPOOLFILE

The DB_MPOOLFILE handle references an open file in the shared memory buffer pool of the database environment. The handle is not free-threaded. Once the memp_fclose function is called, the handle may not be accessed again, regardless of the function's return.

DB

The DB handle is created by the db_create function and references a single Berkeley DB database, which may or may not be part of a database environment. DB handles are free-threaded if the DB_THREAD flag is specified to the DB->open function when the database is opened, or if the database environment in which the database is opened is free-threaded. The handle should not be closed while any other handle that references the database is in use, e.g., database handles must not be closed while cursor handles into the database remain open, or transactions which include operations on the database have not yet been committed or aborted. Once the DB->close, DB->remove or DB->rename functions are called, the handle may not be accessed again, regardless of the function's return.

DBC

The DBC handle references a cursor into a Berkeley DB database. The handle is not free-threaded and cursors may not span threads nor may cursors be used by more than a single thread. If the cursor is to be used to perform operations on behalf of a transaction, the cursor must be opened and closed within the context of that single transaction. Once DBcursor->c_close has been called, the handle may not be accessed again, regardless of the function's return.

Copyright Sleepycat Software