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>Chapter��8.�� Berkeley DB Architecture</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="index.html" title="Berkeley DB Programmer's Reference Guide" /> 11 <link rel="prev" href="stl_known_issues.html" title="Dbstl known issues" /> 12 <link rel="next" href="arch_progmodel.html" title="Programming model" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Chapter��8.�� 19 Berkeley DB Architecture 20 </th> 21 </tr> 22 <tr> 23 <td width="20%" align="left"><a accesskey="p" href="stl_known_issues.html">Prev</a>��</td> 24 <th width="60%" align="center">��</th> 25 <td width="20%" align="right">��<a accesskey="n" href="arch_progmodel.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="chapter" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title"><a id="arch"></a>Chapter��8.�� 35 Berkeley DB Architecture 36 </h2> 37 </div> 38 </div> 39 </div> 40 <div class="toc"> 41 <p> 42 <b>Table of Contents</b> 43 </p> 44 <dl> 45 <dt> 46 <span class="sect1"> 47 <a href="arch.html#arch_bigpic">The big picture</a> 48 </span> 49 </dt> 50 <dt> 51 <span class="sect1"> 52 <a href="arch_progmodel.html">Programming model</a> 53 </span> 54 </dt> 55 <dt> 56 <span class="sect1"> 57 <a href="arch_apis.html">Programmatic APIs</a> 58 </span> 59 </dt> 60 <dd> 61 <dl> 62 <dt> 63 <span class="sect2"> 64 <a href="arch_apis.html#id1603628">C</a> 65 </span> 66 </dt> 67 <dt> 68 <span class="sect2"> 69 <a href="arch_apis.html#id1603668">C++</a> 70 </span> 71 </dt> 72 <dt> 73 <span class="sect2"> 74 <a href="arch_apis.html#id1603511">STL</a> 75 </span> 76 </dt> 77 <dt> 78 <span class="sect2"> 79 <a href="arch_apis.html#id1603399">Java</a> 80 </span> 81 </dt> 82 <dt> 83 <span class="sect2"> 84 <a href="arch_apis.html#id1603369">Dbm/Ndbm, Hsearch</a> 85 </span> 86 </dt> 87 </dl> 88 </dd> 89 <dt> 90 <span class="sect1"> 91 <a href="arch_script.html">Scripting languages</a> 92 </span> 93 </dt> 94 <dd> 95 <dl> 96 <dt> 97 <span class="sect2"> 98 <a href="arch_script.html#id1603486">Perl</a> 99 </span> 100 </dt> 101 <dt> 102 <span class="sect2"> 103 <a href="arch_script.html#id1603736">PHP</a> 104 </span> 105 </dt> 106 <dt> 107 <span class="sect2"> 108 <a href="arch_script.html#id1603909">Tcl</a> 109 </span> 110 </dt> 111 </dl> 112 </dd> 113 <dt> 114 <span class="sect1"> 115 <a href="arch_utilities.html">Supporting utilities</a> 116 </span> 117 </dt> 118 </dl> 119 </div> 120 <div class="sect1" lang="en" xml:lang="en"> 121 <div class="titlepage"> 122 <div> 123 <div> 124 <h2 class="title" style="clear: both"><a id="arch_bigpic"></a>The big picture</h2> 125 </div> 126 </div> 127 </div> 128 <p>The previous chapters in this Reference Guide have described 129applications that use the Berkeley DB access methods for fast data storage 130and retrieval. The applications described in the following chapters 131are similar in nature to the access method applications, but they are 132also threaded and/or recoverable in the face of application or system 133failure.</p> 134 <p>Application code that uses only the Berkeley DB access methods might appear 135as follows:</p> 136 <pre class="programlisting">switch (ret = dbp->/put(dbp, NULL, &key, &data, 0)) { 137case 0: 138 printf("db: %s: key stored.\n", (char *)key.data); 139 break; 140default: 141 dbp->/err(dbp, ret, "dbp->/put"); 142 exit (1); 143}</pre> 144 <p>The underlying Berkeley DB architecture that supports this is</p> 145 <div class="mediaobject"> 146 <img src="arch_smallpic.gif" /> 147 </div> 148 <p>As you can see from this diagram, the application makes calls into the 149access methods, and the access methods use the underlying shared memory 150buffer cache to hold recently used file pages in main memory.</p> 151 <p>When applications require recoverability, their calls to the Access 152Methods must be wrapped in calls to the transaction subsystem. The 153application must inform Berkeley DB where to begin and end transactions, and 154must be prepared for the possibility that an operation may fail at any 155particular time, causing the transaction to abort.</p> 156 <p>An example of transaction-protected code might appear as follows:</p> 157 <pre class="programlisting">for (fail = 0;;) { 158 /* Begin the transaction. */ 159 if ((ret = dbenv->/txn_begin(dbenv, NULL, &tid, 0)) != 0) { 160 dbenv->/err(dbenv, ret, "dbenv->/txn_begin"); 161 exit (1); 162 } 163 164 /* Store the key. */ 165 switch (ret = dbp->/put(dbp, tid, &key, &data, 0)) { 166 case 0: 167 /* Success: commit the change. */ 168 printf("db: %s: key stored.\n", (char *)key.data); 169 if ((ret = tid->/commit(tid, 0)) != 0) { 170 dbenv->/err(dbenv, ret, "DB_TXN->/commit"); 171 exit (1); 172 } 173 return (0); 174 case DB_LOCK_DEADLOCK: 175 default: 176 /* Failure: retry the operation. */ 177 if ((t_ret = tid->/abort(tid)) != 0) { 178 dbenv->/err(dbenv, t_ret, "DB_TXN->/abort"); 179 exit (1); 180 } 181 if (fail++ == MAXIMUM_RETRY) 182 return (ret); 183 continue; 184 } 185}</pre> 186 <p>In this example, the same operation is being done as before; however, 187it is wrapped in transaction calls. The transaction is started with 188<a href="../api_reference/C/txnbegin.html" class="olink">DB_ENV->txn_begin()</a> and finished with <a href="../api_reference/C/txncommit.html" class="olink">DB_TXN->commit()</a>. If the 189operation fails due to a deadlock, the transaction is aborted using 190<a href="../api_reference/C/txnabort.html" class="olink">DB_TXN->abort()</a>, after which the operation may be retried.</p> 191 <p>There are actually five major subsystems in Berkeley DB, as follows:</p> 192 <div class="variablelist"> 193 <dl> 194 <dt> 195 <span class="term">Access Methods</span> 196 </dt> 197 <dd>The access methods subsystem provides general-purpose support for 198creating and accessing database files formatted as Btrees, Hashed files, 199and Fixed- and Variable-length records. These modules are useful in 200the absence of transactions for applications that need fast formatted 201file support. See <a href="../api_reference/C/dbopen.html" class="olink">DB->open()</a> and <a href="../api_reference/C/dbcursor.html" class="olink">DB->cursor()</a> for more 202information. These functions were already discussed in detail in the 203previous chapters.</dd> 204 <dt> 205 <span class="term">Memory Pool</span> 206 </dt> 207 <dd>The Memory Pool subsystem is the general-purpose shared memory buffer pool 208used by Berkeley DB. This is the shared memory cache that allows multiple 209processes and threads within processes to share access to databases. This 210module is useful outside of the Berkeley DB package for processes that require 211portable, page-oriented, cached, shared file access.</dd> 212 <dt> 213 <span class="term">Transaction</span> 214 </dt> 215 <dd>The Transaction subsystem allows a group of database changes to be 216treated as an atomic unit so that either all of the changes are done, 217or none of the changes are done. The transaction subsystem implements 218the Berkeley DB transaction model. This module is useful outside of the Berkeley DB 219package for processes that want to transaction-protect their own data 220modifications.</dd> 221 <dt> 222 <span class="term">Locking</span> 223 </dt> 224 <dd>The Locking subsystem is the general-purpose lock manager used by Berkeley DB. 225This module is useful outside of the Berkeley DB package for processes that 226require a portable, fast, configurable lock manager.</dd> 227 <dt> 228 <span class="term">Logging</span> 229 </dt> 230 <dd>The Logging subsystem is the write-ahead logging used to support the 231Berkeley DB transaction model. It is largely specific to the Berkeley DB package, 232and unlikely to be useful elsewhere except as a supporting module for 233the Berkeley DB transaction subsystem.</dd> 234 </dl> 235 </div> 236 <p>Here is a more complete picture of the Berkeley DB library:</p> 237 <div class="mediaobject"> 238 <img src="arch_bigpic.gif" /> 239 </div> 240 <p>In this model, the application makes calls to the access methods and to 241the Transaction subsystem. The access methods and Transaction subsystems 242in turn make calls into the Memory Pool, Locking and Logging subsystems 243on behalf of the application.</p> 244 <p>The underlying subsystems can be used independently by applications. 245For example, the Memory Pool subsystem can be used apart from the rest 246of Berkeley DB by applications simply wanting a shared memory buffer pool, or 247the Locking subsystem may be called directly by applications that are 248doing their own locking outside of Berkeley DB. However, this usage is not 249common, and most applications will either use only the access methods 250subsystem, or the access methods subsystem wrapped in calls to the Berkeley DB 251transaction interfaces.</p> 252 </div> 253 </div> 254 <div class="navfooter"> 255 <hr /> 256 <table width="100%" summary="Navigation footer"> 257 <tr> 258 <td width="40%" align="left"><a accesskey="p" href="stl_known_issues.html">Prev</a>��</td> 259 <td width="20%" align="center">��</td> 260 <td width="40%" align="right">��<a accesskey="n" href="arch_progmodel.html">Next</a></td> 261 </tr> 262 <tr> 263 <td width="40%" align="left" valign="top">Dbstl known issues��</td> 264 <td width="20%" align="center"> 265 <a accesskey="h" href="index.html">Home</a> 266 </td> 267 <td width="40%" align="right" valign="top">��Programming model</td> 268 </tr> 269 </table> 270 </div> 271 </body> 272</html> 273
