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

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

Prev	Chapter 15. - Programmer Notes -	Chapter 15. Programmer Notes	Next

@@ -49,19 +50,20 @@ lists those handles, their scope, and whether they are free-threaded

- The DB_ENV handle, created by the db_env_create() method, refers - to a Berkeley DB database environment — a collection - of Berkeley DB subsystems, log files and databases. DB_ENV - handles are free-threaded if the DB_THREAD flag is specified - to the DB_ENV->open() method when the - environment is opened. The handle should not be closed - while any other handle remains open that is using it as a - reference (for example, DB, TXN). Once either the - DB_ENV->close() or DB_ENV->remove() methods - are called, the handle may not be accessed again, - regardless of the method's return. -

+ The DB_ENV handle, created by the db_env_create() + method, refers to a Berkeley DB database + environment — a collection of Berkeley DB + subsystems, log files and databases. DB_ENV handles + are free-threaded if the DB_THREAD flag is + specified to the DB_ENV->open() method when the + environment is opened. The handle should not be + closed while any other handle remains open that is + using it as a reference (for example, DB, + TXN). Once either the DB_ENV->close() or DB_ENV->remove() + methods are called, the handle may not be accessed + again, regardless of the method's return. +

@@ -69,25 +71,29 @@ lists those handles, their scope, and whether they are free-threaded

- The TXN handle, created by the DB_ENV->txn_begin() method, refers to a - single transaction. The handle is not free-threaded. - Transactions may span threads, but only serially, that is, the - application must serialize access to the TXN handles. In the - case of nested transactions, since all child transactions are - part of the same parent transaction, they must observe the same - constraints. That is, children may execute in different threads - only if each child executes serially. -

- Once the DB_TXN->abort() or DB_TXN->commit() methods are called, the - handle may not be accessed again, regardless of the method's - return. In addition, parent transactions may not issue any - Berkeley DB operations while they have active child - transactions (child transactions that have not yet been - committed or aborted) except for DB_ENV->txn_begin(), DB_TXN->abort() and - DB_TXN->commit(). -

+ The TXN handle, created by the DB_ENV->txn_begin() + method, refers to a single transaction. The handle + is not free-threaded. Transactions may span + threads, but only serially, that is, the + application must serialize access to the TXN + handles. In the case of nested transactions, since + all child transactions are part of the same parent + transaction, they must observe the same + constraints. That is, children may execute in + different threads only if each child executes + serially. +

+ Once the DB_TXN->abort() or DB_TXN->commit() methods are + called, the handle may not be accessed again, + regardless of the method's return. In addition, + parent transactions may not issue any Berkeley DB + operations while they have active child + transactions (child transactions that have not yet + been committed or aborted) except for DB_ENV->txn_begin(), + DB_TXN->abort() and DB_TXN->commit(). +

@@ -95,12 +101,13 @@ lists those handles, their scope, and whether they are free-threaded

- The DB_LOGC handle refers to a cursor into the log files. The - handle is not free-threaded. Once the DB_LOGC->close() method is - called, the handle may not be accessed again, regardless of the - method's return. -

+ The DB_LOGC handle refers to a cursor into the + log files. The handle is not free-threaded. Once + the DB_LOGC->close() method is called, the handle may + not be accessed again, regardless of the method's + return. +

@@ -109,12 +116,13 @@ lists those handles, their scope, and whether they are free-threaded

- The DB_MPOOLFILE handle refers to an open file in the shared memory - buffer pool of the database environment. The handle is not - free-threaded. Once the DB_MPOOLFILE->close() method is called, the - handle may not be accessed again, regardless of the method's - return. -

+ The DB_MPOOLFILE handle refers to an open file in the + shared memory buffer pool of the database + environment. The handle is not free-threaded. Once + the DB_MPOOLFILE->close() method is called, the handle may + not be accessed again, regardless of the method's + return. +

@@ -122,21 +130,25 @@ lists those handles, their scope, and whether they are free-threaded

- The DB handle, created by the db_create() method, refers to 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() method 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 refers to the database is in - use; for example, database handles should be left open while - cursor handles into the database remain open, or transactions - that include operations on the database have not yet been - committed or aborted. Once the DB->close(), DB->remove() or - DB->rename() methods are called, the handle may not be accessed - again, regardless of the method's return. -

+ The DB handle, created by the db_create() + method, refers to 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() + method 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 refers to the + database is in use; for example, database handles + should be left open while cursor handles into the + database remain open, or transactions that include + operations on the database have not yet been + committed or aborted. Once the DB->close(), + DB->remove() or DB->rename() methods are called, the + handle may not be accessed again, regardless of + the method's return. +

@@ -144,17 +156,19 @@ lists those handles, their scope, and whether they are free-threaded

- The DBC handle refers to a cursor into a Berkeley DB - database. The handle is not free-threaded. Cursors may span - threads, but only serially, that is, the application must - serialize access to the DBC handles. 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 DBC->close() has been called, the - handle may not be accessed again, regardless of the method's - return. -

+ The DBC handle refers to a cursor into a + Berkeley DB database. The handle is not + free-threaded. Cursors may span threads, but only + serially, that is, the application must serialize + access to the DBC handles. 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 DBC->close() has been called, the handle may + not be accessed again, regardless of the method's + return. +