mirror of
https://github.com/berkeleydb/libdb.git
synced 2024-11-16 17:16:25 +00:00
182 lines
9.8 KiB
HTML
182 lines
9.8 KiB
HTML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
|
||
<title>Berkeley DB handles</title>
|
||
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
|
||
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
|
||
<link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
|
||
<link rel="up" href="program.html" title="Chapter 15. Programmer Notes" />
|
||
<link rel="prev" href="program_mt.html" title="Multithreaded applications" />
|
||
<link rel="next" href="program_namespace.html" title="Name spaces" />
|
||
</head>
|
||
<body>
|
||
<div xmlns="" class="navheader">
|
||
<div class="libver">
|
||
<p>Library Version 11.2.5.2</p>
|
||
</div>
|
||
<table width="100%" summary="Navigation header">
|
||
<tr>
|
||
<th colspan="3" align="center">Berkeley DB handles</th>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" align="left"><a accesskey="p" href="program_mt.html">Prev</a> </td>
|
||
<th width="60%" align="center">Chapter 15.
|
||
Programmer Notes
|
||
</th>
|
||
<td width="20%" align="right"> <a accesskey="n" href="program_namespace.html">Next</a></td>
|
||
</tr>
|
||
</table>
|
||
<hr />
|
||
</div>
|
||
<div class="sect1" lang="en" xml:lang="en">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div>
|
||
<h2 class="title" style="clear: both"><a id="program_scope"></a>Berkeley DB handles</h2>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<p>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).</p>
|
||
<div class="variablelist">
|
||
<dl>
|
||
<dt>
|
||
<span class="term">
|
||
<a href="../api_reference/C/env.html" class="olink">DB_ENV</a>
|
||
</span>
|
||
</dt>
|
||
<dd>
|
||
<p>
|
||
The <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> handle, created by the <a href="../api_reference/C/envcreate.html" class="olink">db_env_create()</a> method, refers
|
||
to a Berkeley DB database environment — a collection
|
||
of Berkeley DB subsystems, log files and databases. <a href="../api_reference/C/env.html" class="olink">DB_ENV</a>
|
||
handles are free-threaded if the <a href="../api_reference/C/envopen.html#envopen_DB_THREAD" class="olink">DB_THREAD</a> flag is specified
|
||
to the <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> 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, <a href="../api_reference/C/db.html" class="olink">DB</a>, <a href="../api_reference/C/txn.html" class="olink">TXN</a>). Once either the
|
||
<a href="../api_reference/C/envclose.html" class="olink">DB_ENV->close()</a> or <a href="../api_reference/C/envremove.html" class="olink">DB_ENV->remove()</a> methods
|
||
are called, the handle may not be accessed again,
|
||
regardless of the method's return.
|
||
</p>
|
||
</dd>
|
||
<dt>
|
||
<span class="term">
|
||
<a href="../api_reference/C/txn.html" class="olink">TXN</a>
|
||
</span>
|
||
</dt>
|
||
<dd>
|
||
<p>
|
||
The <a href="../api_reference/C/txn.html" class="olink">TXN</a> handle, created by the <a href="../api_reference/C/txnbegin.html" class="olink">DB_ENV->txn_begin()</a> 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 <a href="../api_reference/C/txn.html" class="olink">TXN</a> 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.
|
||
</p>
|
||
<p>
|
||
Once the <a href="../api_reference/C/txnabort.html" class="olink">DB_TXN->abort()</a> or <a href="../api_reference/C/txncommit.html" class="olink">DB_TXN->commit()</a> 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 <a href="../api_reference/C/txnbegin.html" class="olink">DB_ENV->txn_begin()</a>, <a href="../api_reference/C/txnabort.html" class="olink">DB_TXN->abort()</a> and
|
||
<a href="../api_reference/C/txncommit.html" class="olink">DB_TXN->commit()</a>.
|
||
</p>
|
||
</dd>
|
||
<dt>
|
||
<span class="term">
|
||
<a href="../api_reference/C/logc.html" class="olink">DB_LOGC</a>
|
||
</span>
|
||
</dt>
|
||
<dd>
|
||
<p>
|
||
The <a href="../api_reference/C/logc.html" class="olink">DB_LOGC</a> handle refers to a cursor into the log files. The
|
||
handle is not free-threaded. Once the <a href="../api_reference/C/logcclose.html" class="olink">DB_LOGC->close()</a> method is
|
||
called, the handle may not be accessed again, regardless of the
|
||
method's return.
|
||
</p>
|
||
</dd>
|
||
<dt>
|
||
<span class="term">
|
||
<a href="../api_reference/C/memp.html" class="olink">DB_MPOOLFILE</a>
|
||
</span>
|
||
</dt>
|
||
<dd>
|
||
<p>
|
||
The <a href="../api_reference/C/memp.html" class="olink">DB_MPOOLFILE</a> handle refers to an open file in the shared memory
|
||
buffer pool of the database environment. The handle is not
|
||
free-threaded. Once the <a href="../api_reference/C/mempfclose.html" class="olink">DB_MPOOLFILE->close()</a> method is called, the
|
||
handle may not be accessed again, regardless of the method's
|
||
return.
|
||
</p>
|
||
</dd>
|
||
<dt>
|
||
<span class="term">
|
||
<a href="../api_reference/C/db.html" class="olink">DB</a>
|
||
</span>
|
||
</dt>
|
||
<dd>
|
||
<p>
|
||
The <a href="../api_reference/C/db.html" class="olink">DB</a> handle, created by the <a href="../api_reference/C/dbcreate.html" class="olink">db_create()</a> method, refers to a
|
||
single Berkeley DB database, which may or may not be part of a
|
||
database environment. <a href="../api_reference/C/db.html" class="olink">DB</a> handles are free-threaded if the
|
||
<a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> flag is specified to the <a href="../api_reference/C/dbopen.html" class="olink">DB->open()</a> 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 <a href="../api_reference/C/dbclose.html" class="olink">DB->close()</a>, <a href="../api_reference/C/dbremove.html" class="olink">DB->remove()</a> or
|
||
<a href="../api_reference/C/dbrename.html" class="olink">DB->rename()</a> methods are called, the handle may not be accessed
|
||
again, regardless of the method's return.
|
||
</p>
|
||
</dd>
|
||
<dt>
|
||
<span class="term">
|
||
<a href="../api_reference/C/dbc.html" class="olink">DBC</a>
|
||
</span>
|
||
</dt>
|
||
<dd>
|
||
<p>
|
||
The <a href="../api_reference/C/dbc.html" class="olink">DBC</a> 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 <a href="../api_reference/C/dbc.html" class="olink">DBC</a> 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 <a href="../api_reference/C/dbcclose.html" class="olink">DBC->close()</a> has been called, the
|
||
handle may not be accessed again, regardless of the method's
|
||
return.
|
||
</p>
|
||
</dd>
|
||
</dl>
|
||
</div>
|
||
</div>
|
||
<div class="navfooter">
|
||
<hr />
|
||
<table width="100%" summary="Navigation footer">
|
||
<tr>
|
||
<td width="40%" align="left"><a accesskey="p" href="program_mt.html">Prev</a> </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="u" href="program.html">Up</a>
|
||
</td>
|
||
<td width="40%" align="right"> <a accesskey="n" href="program_namespace.html">Next</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="40%" align="left" valign="top">Multithreaded applications </td>
|
||
<td width="20%" align="center">
|
||
<a accesskey="h" href="index.html">Home</a>
|
||
</td>
|
||
<td width="40%" align="right" valign="top"> Name spaces</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html>
|