1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>Berkeley DB handles</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" /> 10 <link rel="up" href="program.html" title="Chapter��14.�� Programmer Notes" /> 11 <link rel="prev" href="program_mt.html" title="Multithreaded applications" /> 12 <link rel="next" href="program_namespace.html" title="Name spaces" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Berkeley DB handles</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="program_mt.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��14.�� 23 Programmer Notes 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="program_namespace.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="program_scope"></a>Berkeley DB handles</h2> 35 </div> 36 </div> 37 </div> 38 <p>The Berkeley DB library has a number of object handles. The following table 39lists those handles, their scope, and whether they are free-threaded 40(that is, whether multiple threads within a process can share them).</p> 41 <div class="variablelist"> 42 <dl> 43 <dt> 44 <span class="term"> 45 <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> 46 </span> 47 </dt> 48 <dd> 49 <p> 50 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 51 to a Berkeley DB database environment ��� a collection 52 of Berkeley DB subsystems, log files and databases. <a href="../api_reference/C/env.html" class="olink">DB_ENV</a> 53 handles are free-threaded if the <a href="../api_reference/C/dbopen.html#open_DB_THREAD" class="olink">DB_THREAD</a> flag is specified 54 to the <a href="../api_reference/C/envopen.html" class="olink">DB_ENV->open()</a> method when the 55 environment is opened. The handle should not be closed 56 while any other handle remains open that is using it as a 57 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 58 <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 59 are called, the handle may not be accessed again, 60 regardless of the method's return. 61 </p> 62 </dd> 63 <dt> 64 <span class="term"> 65 <a href="../api_reference/C/txn.html" class="olink">TXN</a> 66 </span> 67 </dt> 68 <dd> 69 <p> 70 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 71 single transaction. The handle is not free-threaded. 72 Transactions may span threads, but only serially, that is, the 73 application must serialize access to the <a href="../api_reference/C/txn.html" class="olink">TXN</a> handles. In the 74 case of nested transactions, since all child transactions are 75 part of the same parent transaction, they must observe the same 76 constraints. That is, children may execute in different threads 77 only if each child executes serially. 78 </p> 79 <p> 80 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 81 handle may not be accessed again, regardless of the method's 82 return. In addition, parent transactions may not issue any 83 Berkeley DB operations while they have active child 84 transactions (child transactions that have not yet been 85 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 86 <a href="../api_reference/C/txncommit.html" class="olink">DB_TXN->commit()</a>. 87 </p> 88 </dd> 89 <dt> 90 <span class="term"> 91 <a href="../api_reference/C/logc.html" class="olink">DB_LOGC</a> 92 </span> 93 </dt> 94 <dd> 95 <p> 96 The <a href="../api_reference/C/logc.html" class="olink">DB_LOGC</a> handle refers to a cursor into the log files. The 97 handle is not free-threaded. Once the <a href="../api_reference/C/logcclose.html" class="olink">DB_LOGC->close()</a> method is 98 called, the handle may not be accessed again, regardless of the 99 method's return. 100 </p> 101 </dd> 102 <dt> 103 <span class="term"> 104 <a href="../api_reference/C/memp.html" class="olink">DB_MPOOLFILE</a> 105 </span> 106 </dt> 107 <dd> 108 <p> 109 The <a href="../api_reference/C/memp.html" class="olink">DB_MPOOLFILE</a> handle refers to an open file in the shared memory 110 buffer pool of the database environment. The handle is not 111 free-threaded. Once the <a href="../api_reference/C/mempfclose.html" class="olink">DB_MPOOLFILE->close()</a> method is called, the 112 handle may not be accessed again, regardless of the method's 113 return. 114 </p> 115 </dd> 116 <dt> 117 <span class="term"> 118 <a href="../api_reference/C/db.html" class="olink">DB</a> 119 </span> 120 </dt> 121 <dd> 122 <p> 123 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 124 single Berkeley DB database, which may or may not be part of a 125 database environment. <a href="../api_reference/C/db.html" class="olink">DB</a> handles are free-threaded if the 126 <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/envopen.html" class="olink">DB_ENV->open()</a> method when the 127 database is opened or if the database environment in which the 128 database is opened is free-threaded. The handle should not be 129 closed while any other handle that refers to the database is in 130 use; for example, database handles should be left open while 131 cursor handles into the database remain open, or transactions 132 that include operations on the database have not yet been 133 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 134 <a href="../api_reference/C/dbrename.html" class="olink">DB->rename()</a> methods are called, the handle may not be accessed 135 again, regardless of the method's return. 136 </p> 137 </dd> 138 <dt> 139 <span class="term"> 140 <a href="../api_reference/C/dbc.html" class="olink">DBC</a> 141 </span> 142 </dt> 143 <dd> 144 <p> 145 The <a href="../api_reference/C/dbc.html" class="olink">DBC</a> handle refers to a cursor into a Berkeley DB 146 database. The handle is not free-threaded. Cursors may span 147 threads, but only serially, that is, the application must 148 serialize access to the <a href="../api_reference/C/dbc.html" class="olink">DBC</a> handles. If the cursor is to be 149 used to perform operations on behalf of a transaction, the 150 cursor must be opened and closed within the context of that 151 single transaction. Once <a href="../api_reference/C/dbcclose.html" class="olink">DBC->close()</a> has been called, the 152 handle may not be accessed again, regardless of the method's 153 return. 154 </p> 155 </dd> 156 </dl> 157 </div> 158 </div> 159 <div class="navfooter"> 160 <hr /> 161 <table width="100%" summary="Navigation footer"> 162 <tr> 163 <td width="40%" align="left"><a accesskey="p" href="program_mt.html">Prev</a>��</td> 164 <td width="20%" align="center"> 165 <a accesskey="u" href="program.html">Up</a> 166 </td> 167 <td width="40%" align="right">��<a accesskey="n" href="program_namespace.html">Next</a></td> 168 </tr> 169 <tr> 170 <td width="40%" align="left" valign="top">Multithreaded applications��</td> 171 <td width="20%" align="center"> 172 <a accesskey="h" href="index.html">Home</a> 173 </td> 174 <td width="40%" align="right" valign="top">��Name spaces</td> 175 </tr> 176 </table> 177 </div> 178 </body> 179</html> 180