diff options
Diffstat (limited to 'docs/programmer_reference/arch.html')
| -rw-r--r-- | docs/programmer_reference/arch.html | 262 |
1 files changed, 155 insertions, 107 deletions
diff --git a/docs/programmer_reference/arch.html b/docs/programmer_reference/arch.html index 9c56c602..4f69a48c 100644 --- a/docs/programmer_reference/arch.html +++ b/docs/programmer_reference/arch.html @@ -14,13 +14,11 @@ <body> <div xmlns="" class="navheader"> <div class="libver"> - <p>Library Version 11.2.5.3</p> + <p>Library Version 12.1.6.1</p> </div> <table width="100%" summary="Navigation header"> <tr> - <th colspan="3" align="center">Chapter 8. - Berkeley DB Architecture - </th> + <th colspan="3" align="center">Chapter 8. Berkeley DB Architecture </th> </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="stl_known_issues.html">Prev</a> </td> @@ -34,9 +32,7 @@ <div class="titlepage"> <div> <div> - <h2 class="title"><a id="arch"></a>Chapter 8. - Berkeley DB Architecture - </h2> + <h2 class="title"><a id="arch"></a>Chapter 8. Berkeley DB Architecture </h2> </div> </div> </div> @@ -64,27 +60,27 @@ <dl> <dt> <span class="sect2"> - <a href="arch_apis.html#idp1156848">C</a> + <a href="arch_apis.html#idp1016624">C</a> </span> </dt> <dt> <span class="sect2"> - <a href="arch_apis.html#idp1467704">C++</a> + <a href="arch_apis.html#idp1020280">C++</a> </span> </dt> <dt> <span class="sect2"> - <a href="arch_apis.html#idp1468224">STL</a> + <a href="arch_apis.html#idp1041496">STL</a> </span> </dt> <dt> <span class="sect2"> - <a href="arch_apis.html#idp1467768">Java</a> + <a href="arch_apis.html#idp1042312">Java</a> </span> </dt> <dt> <span class="sect2"> - <a href="arch_apis.html#idp1485576">Dbm/Ndbm, Hsearch</a> + <a href="arch_apis.html#idp1061592">Dbm/Ndbm, Hsearch</a> </span> </dt> </dl> @@ -98,17 +94,17 @@ <dl> <dt> <span class="sect2"> - <a href="arch_script.html#idp1461432">Perl</a> + <a href="arch_script.html#idp1034968">Perl</a> </span> </dt> <dt> <span class="sect2"> - <a href="arch_script.html#idp1460536">PHP</a> + <a href="arch_script.html#idp1033112">PHP</a> </span> </dt> <dt> <span class="sect2"> - <a href="arch_script.html#idp1477280">Tcl</a> + <a href="arch_script.html#idp1052216">Tcl</a> </span> </dt> </dl> @@ -128,130 +124,182 @@ </div> </div> </div> - <p>The previous chapters in this Reference Guide have described -applications that use the Berkeley DB access methods for fast data storage -and retrieval. The applications described in the following chapters -are similar in nature to the access method applications, but they are -also threaded and/or recoverable in the face of application or system -failure.</p> - <p>Application code that uses only the Berkeley DB access methods might appear -as follows:</p> + <p> + The previous chapters in this Reference Guide have described + applications that use the Berkeley DB access methods for fast + data storage and retrieval. The applications described in the + following chapters are similar in nature to the access method + applications, but they are also threaded and/or recoverable in + the face of application or system failure. + </p> + <p> + Application code that uses only the Berkeley DB access + methods might appear as follows: + </p> <pre class="programlisting">switch (ret = dbp->/put(dbp, NULL, &key, &data, 0)) { case 0: - printf("db: %s: key stored.\n", (char *)key.data); - break; + printf("db: %s: key stored.\n", (char *)key.data); + break; default: - dbp->/err(dbp, ret, "dbp->/put"); - exit (1); + dbp->/err(dbp, ret, "dbp->/put"); + exit (1); }</pre> - <p>The underlying Berkeley DB architecture that supports this is</p> + <p> + The underlying Berkeley DB architecture that supports this + is + </p> <div class="mediaobject"> <img src="arch_smallpic.gif" /> </div> - <p>As you can see from this diagram, the application makes calls into the -access methods, and the access methods use the underlying shared memory -buffer cache to hold recently used file pages in main memory.</p> - <p>When applications require recoverability, their calls to the Access -Methods must be wrapped in calls to the transaction subsystem. The -application must inform Berkeley DB where to begin and end transactions, and -must be prepared for the possibility that an operation may fail at any -particular time, causing the transaction to abort.</p> - <p>An example of transaction-protected code might appear as follows:</p> + <p> + As you can see from this diagram, the application makes + calls into the access methods, and the access methods use the + underlying shared memory buffer cache to hold recently used + file pages in main memory. + </p> + <p> + When applications require recoverability, their calls to the + Access Methods must be wrapped in calls to the transaction + subsystem. The application must inform Berkeley DB where to + begin and end transactions, and must be prepared for the + possibility that an operation may fail at any particular time, + causing the transaction to abort. + </p> + <p> + An example of transaction-protected code might appear as + follows: + </p> <pre class="programlisting">for (fail = 0;;) { - /* Begin the transaction. */ - if ((ret = dbenv->/txn_begin(dbenv, NULL, &tid, 0)) != 0) { - dbenv->/err(dbenv, ret, "dbenv->/txn_begin"); - exit (1); - } + /* Begin the transaction. */ + if ((ret = dbenv->/txn_begin(dbenv, NULL, &tid, 0)) != 0) { + dbenv->/err(dbenv, ret, "dbenv->/txn_begin"); + exit (1); + } - /* Store the key. */ - switch (ret = dbp->/put(dbp, tid, &key, &data, 0)) { - case 0: - /* Success: commit the change. */ - printf("db: %s: key stored.\n", (char *)key.data); - if ((ret = tid->/commit(tid, 0)) != 0) { - dbenv->/err(dbenv, ret, "DB_TXN->/commit"); - exit (1); - } - return (0); - case DB_LOCK_DEADLOCK: - default: - /* Failure: retry the operation. */ - if ((t_ret = tid->/abort(tid)) != 0) { - dbenv->/err(dbenv, t_ret, "DB_TXN->/abort"); - exit (1); - } - if (fail++ == MAXIMUM_RETRY) - return (ret); - continue; - } + /* Store the key. */ + switch (ret = dbp->/put(dbp, tid, &key, &data, 0)) { + case 0: + /* Success: commit the change. */ + printf("db: %s: key stored.\n", (char *)key.data); + if ((ret = tid->/commit(tid, 0)) != 0) { + dbenv->/err(dbenv, ret, "DB_TXN->/commit"); + exit (1); + } + return (0); + case DB_LOCK_DEADLOCK: + default: + /* Failure: retry the operation. */ + if ((t_ret = tid->/abort(tid)) != 0) { + dbenv->/err(dbenv, t_ret, "DB_TXN->/abort"); + exit (1); + } + if (fail++ == MAXIMUM_RETRY) + return (ret); + continue; + } }</pre> - <p>In this example, the same operation is being done as before; however, -it is wrapped in transaction calls. The transaction is started with -<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 -operation fails due to a deadlock, the transaction is aborted using -<a href="../api_reference/C/txnabort.html" class="olink">DB_TXN->abort()</a>, after which the operation may be retried.</p> - <p>There are actually five major subsystems in Berkeley DB, as follows:</p> + <p> + In this example, the same operation is being done as before; + however, it is wrapped in transaction calls. The transaction + is started with <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 operation fails due to a deadlock, the transaction is + aborted using <a href="../api_reference/C/txnabort.html" class="olink">DB_TXN->abort()</a>, after which the operation may be + retried. + </p> + <p> + There are actually five major subsystems in Berkeley DB, as + follows: + </p> <div class="variablelist"> <dl> <dt> <span class="term">Access Methods</span> </dt> - <dd>The access methods subsystem provides general-purpose support for -creating and accessing database files formatted as Btrees, Hashed files, -and Fixed- and Variable-length records. These modules are useful in -the absence of transactions for applications that need fast formatted -file 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 -information. These functions were already discussed in detail in the -previous chapters.</dd> + <dd> + The access methods subsystem provides + general-purpose support for creating and accessing + database files formatted as Btrees, Hashed files, and + Fixed- and Variable-length records. These modules are + useful in the absence of transactions for applications + that need fast formatted file 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 information. These functions + were already discussed in detail in the previous + chapters. + </dd> <dt> <span class="term">Memory Pool</span> </dt> - <dd>The Memory Pool subsystem is the general-purpose shared memory buffer pool -used by Berkeley DB. This is the shared memory cache that allows multiple -processes and threads within processes to share access to databases. This -module is useful outside of the Berkeley DB package for processes that require -portable, page-oriented, cached, shared file access.</dd> + <dd> + The Memory Pool subsystem is the general-purpose + shared memory buffer pool used by Berkeley DB. This is + the shared memory cache that allows multiple processes + and threads within processes to share access to + databases. This module is useful outside of the + Berkeley DB package for processes that require + portable, page-oriented, cached, shared file + access. + </dd> <dt> <span class="term">Transaction</span> </dt> - <dd>The Transaction subsystem allows a group of database changes to be -treated as an atomic unit so that either all of the changes are done, -or none of the changes are done. The transaction subsystem implements -the Berkeley DB transaction model. This module is useful outside of the Berkeley DB -package for processes that want to transaction-protect their own data -modifications.</dd> + <dd> + The Transaction subsystem allows a group of + database changes to be treated as an atomic unit so + that either all of the changes are done, or none of + the changes are done. The transaction subsystem + implements the Berkeley DB transaction model. This + module is useful outside of the Berkeley DB package + for processes that want to transaction-protect their + own data modifications. + </dd> <dt> <span class="term">Locking</span> </dt> - <dd>The Locking subsystem is the general-purpose lock manager used by Berkeley DB. -This module is useful outside of the Berkeley DB package for processes that -require a portable, fast, configurable lock manager.</dd> + <dd> + The Locking subsystem is the general-purpose + lock manager used by Berkeley DB. This module is + useful outside of the Berkeley DB package for + processes that require a portable, fast, configurable + lock manager. + </dd> <dt> <span class="term">Logging</span> </dt> - <dd>The Logging subsystem is the write-ahead logging used to support the -Berkeley DB transaction model. It is largely specific to the Berkeley DB package, -and unlikely to be useful elsewhere except as a supporting module for -the Berkeley DB transaction subsystem.</dd> + <dd> + The Logging subsystem is the write-ahead logging + used to support the Berkeley DB transaction model. It + is largely specific to the Berkeley DB package, and + unlikely to be useful elsewhere except as a supporting + module for the Berkeley DB transaction + subsystem. + </dd> </dl> </div> - <p>Here is a more complete picture of the Berkeley DB library:</p> + <p> + Here is a more complete picture of the Berkeley DB + library: + </p> <div class="mediaobject"> <img src="arch_bigpic.gif" /> </div> - <p>In this model, the application makes calls to the access methods and to -the Transaction subsystem. The access methods and Transaction subsystems -in turn make calls into the Memory Pool, Locking and Logging subsystems -on behalf of the application.</p> - <p>The underlying subsystems can be used independently by applications. -For example, the Memory Pool subsystem can be used apart from the rest -of Berkeley DB by applications simply wanting a shared memory buffer pool, or -the Locking subsystem may be called directly by applications that are -doing their own locking outside of Berkeley DB. However, this usage is not -common, and most applications will either use only the access methods -subsystem, or the access methods subsystem wrapped in calls to the Berkeley DB -transaction interfaces.</p> + <p> + In this model, the application makes calls to the access + methods and to the Transaction subsystem. The access methods + and Transaction subsystems in turn make calls into the Memory + Pool, Locking and Logging subsystems on behalf of the + application. + </p> + <p> + The underlying subsystems can be used independently by + applications. For example, the Memory Pool subsystem can be + used apart from the rest of Berkeley DB by applications simply + wanting a shared memory buffer pool, or the Locking subsystem + may be called directly by applications that are doing their + own locking outside of Berkeley DB. However, this usage is not + common, and most applications will either use only the access + methods subsystem, or the access methods subsystem wrapped in + calls to the Berkeley DB transaction interfaces. + </p> </div> </div> <div class="navfooter"> |