diff options
| author | Lorry Tar Creator <lorry-tar-importer@baserock.org> | 2015-02-17 17:25:57 +0000 |
|---|---|---|
| committer | <> | 2015-03-17 16:26:24 +0000 |
| commit | 780b92ada9afcf1d58085a83a0b9e6bc982203d1 (patch) | |
| tree | 598f8b9fa431b228d29897e798de4ac0c1d3d970 /docs/programmer_reference/apprec.html | |
| parent | 7a2660ba9cc2dc03a69ddfcfd95369395cc87444 (diff) | |
| download | berkeleydb-master.tar.gz | |
Diffstat (limited to 'docs/programmer_reference/apprec.html')
| -rw-r--r-- | docs/programmer_reference/apprec.html | 173 |
1 files changed, 102 insertions, 71 deletions
diff --git a/docs/programmer_reference/apprec.html b/docs/programmer_reference/apprec.html index a74c3f77..4792b862 100644 --- a/docs/programmer_reference/apprec.html +++ b/docs/programmer_reference/apprec.html @@ -14,13 +14,12 @@ <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 14. - Application Specific Logging and Recovery - </th> + <th colspan="3" align="center">Chapter 14. Application Specific Logging and + Recovery </th> </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="xa_faq.html">Prev</a> </td> @@ -34,9 +33,8 @@ <div class="titlepage"> <div> <div> - <h2 class="title"><a id="apprec"></a>Chapter 14. - Application Specific Logging and Recovery - </h2> + <h2 class="title"><a id="apprec"></a>Chapter 14. Application Specific Logging and + Recovery </h2> </div> </div> </div> @@ -47,17 +45,20 @@ <dl> <dt> <span class="sect1"> - <a href="apprec.html#apprec_intro">Introduction to application specific logging and recovery</a> + <a href="apprec.html#apprec_intro">Introduction to application + specific logging and recovery</a> </span> </dt> <dt> <span class="sect1"> - <a href="apprec_def.html">Defining application-specific log records</a> + <a href="apprec_def.html">Defining application-specific log + records</a> </span> </dt> <dt> <span class="sect1"> - <a href="apprec_auto.html">Automatically generated functions</a> + <a href="apprec_auto.html">Automatically generated + functions</a> </span> </dt> <dt> @@ -71,69 +72,98 @@ <div class="titlepage"> <div> <div> - <h2 class="title" style="clear: both"><a id="apprec_intro"></a>Introduction to application specific logging and recovery</h2> + <h2 class="title" style="clear: both"><a id="apprec_intro"></a>Introduction to application + specific logging and recovery</h2> </div> </div> </div> - <p>It is possible to use the Locking, Logging and Transaction subsystems -of Berkeley DB to provide transaction semantics on objects other than those -described by the Berkeley DB access methods. In these cases, the application -will need application-specific logging and recovery functions.</p> - <p>For example, consider an application that provides transaction semantics -on data stored in plain text files accessed using the POSIX read and -write system calls. The read and write operations for which transaction -protection is desired will be bracketed by calls to the standard Berkeley DB -transactional interfaces, <a href="../api_reference/C/txnbegin.html" class="olink">DB_ENV->txn_begin()</a> and <a href="../api_reference/C/txncommit.html" class="olink">DB_TXN->commit()</a>, and -the transaction's locker ID will be used to acquire relevant read and -write locks.</p> - <p>Before data is accessed, the application must make a call to the lock -manager, <a href="../api_reference/C/lockget.html" class="olink">DB_ENV->lock_get()</a>, for a lock of the appropriate type (for -example, read) on the object being locked. The object might be a page -in the file, a byte, a range of bytes, or some key. It is up to the -application to ensure that appropriate locks are acquired. Before a -write is performed, the application should acquire a write lock on the -object by making an appropriate call to the lock manager, -<a href="../api_reference/C/lockget.html" class="olink">DB_ENV->lock_get()</a>. Then, the application should make a call to the log -manager, via the automatically-generated log-writing function described -as follows. This record should contain enough information to redo the -operation in case of failure after commit and to undo the operation in -case of abort.</p> - <p>When designing applications that will use the log subsystem, it is -important to remember that the application is responsible for providing -any necessary structure to the log record. For example, the application -must understand what part of the log record is an operation code, what -part identifies the file being modified, what part is redo information, -and what part is undo information.</p> - <p>After the log message is written, the application may issue the write -system call. After all requests are issued, the application may call -<a href="../api_reference/C/txncommit.html" class="olink">DB_TXN->commit()</a>. When <a href="../api_reference/C/txncommit.html" class="olink">DB_TXN->commit()</a> returns, the caller is -guaranteed that all necessary log writes have been written to disk.</p> - <p>At any time before issuing a <a href="../api_reference/C/txncommit.html" class="olink">DB_TXN->commit()</a>, the application may -call <a href="../api_reference/C/txnabort.html" class="olink">DB_TXN->abort()</a>, which will result in restoration of the database -to a consistent pretransaction state. (The application may specify its -own recovery function for this purpose using the -<a href="../api_reference/C/envset_app_dispatch.html" class="olink">DB_ENV->set_app_dispatch()</a> method. The recovery function must be able to -either reapply or undo the update depending on the context, for each -different type of log record. The recovery functions must not use Berkeley DB -methods to access data in the environment as there is no way to -coordinate these accesses with either the aborting transaction or the -updates done by recovery or replication.)</p> - <p>If the application crashes, the recovery process uses the log to restore -the database to a consistent state.</p> - <p>Berkeley DB includes tools to assist in the development of application-specific -logging and recovery. Specifically, given a description of information -to be logged in a family of log records, these tools will automatically -create log-writing functions (functions that marshall their arguments -into a single log record), log-reading functions (functions that read -a log record and unmarshall it into a structure containing fields that -map into the arguments written to the log), log-printing functions -(functions that print the contents of a log record for debugging), and -templates for recovery functions (functions that review log records -during transaction abort or recovery). The tools and generated code -are C-language and POSIX-system based, but the generated code should be -usable on any system, not just POSIX systems.</p> - <p>A sample application that does application-specific recovery is included -in the Berkeley DB distribution, in the directory <code class="filename">examples_c/ex_apprec</code>.</p> + <p> + It is possible to use the Locking, Logging and Transaction + subsystems of Berkeley DB to provide transaction semantics on + objects other than those described by the Berkeley DB access + methods. In these cases, the application will need + application-specific logging and recovery functions. + </p> + <p> + For example, consider an application that provides + transaction semantics on data stored in plain text files + accessed using the POSIX read and write system calls. The read + and write operations for which transaction protection is + desired will be bracketed by calls to the standard Berkeley DB + transactional interfaces, <a href="../api_reference/C/txnbegin.html" class="olink">DB_ENV->txn_begin()</a> and <a href="../api_reference/C/txncommit.html" class="olink">DB_TXN->commit()</a>, and the + transaction's locker ID will be used to acquire relevant read + and write locks. + </p> + <p> + Before data is accessed, the application must make a call to + the lock manager, <a href="../api_reference/C/lockget.html" class="olink">DB_ENV->lock_get()</a>, for a lock of the appropriate + type (for example, read) on the object being locked. The + object might be a page in the file, a byte, a range of bytes, + or some key. It is up to the application to ensure that + appropriate locks are acquired. Before a write is performed, + the application should acquire a write lock on the object by + making an appropriate call to the lock manager, <a href="../api_reference/C/lockget.html" class="olink">DB_ENV->lock_get()</a>. + Then, the application should make a call to the log manager, + via the automatically-generated log-writing function described + as follows. This record should contain enough information to + redo the operation in case of failure after commit and to undo + the operation in case of abort. + </p> + <p> + When designing applications that will use the log subsystem, + it is important to remember that the application is + responsible for providing any necessary structure to the log + record. For example, the application must understand what part + of the log record is an operation code, what part identifies + the file being modified, what part is redo information, and + what part is undo information. + </p> + <p> + After the log message is written, the application may issue + the write system call. After all requests are issued, the + application may call <a href="../api_reference/C/txncommit.html" class="olink">DB_TXN->commit()</a>. When <a href="../api_reference/C/txncommit.html" class="olink">DB_TXN->commit()</a> returns, + the caller is guaranteed that all necessary log writes have + been written to disk. + </p> + <p> + At any time before issuing a <a href="../api_reference/C/txncommit.html" class="olink">DB_TXN->commit()</a>, the application + may call <a href="../api_reference/C/txnabort.html" class="olink">DB_TXN->abort()</a>, which will result in restoration of the + database to a consistent pretransaction state. (The + application may specify its own recovery function for this + purpose using the <a href="../api_reference/C/envset_app_dispatch.html" class="olink">DB_ENV->set_app_dispatch()</a> method. The recovery + function must be able to either reapply or undo the update + depending on the context, for each different type of log + record. The recovery functions must not use Berkeley DB + methods to access data in the environment as there is no way + to coordinate these accesses with either the aborting + transaction or the updates done by recovery or + replication.) + </p> + <p> + If the application crashes, the recovery process uses the + log to restore the database to a consistent state. + </p> + <p> + Berkeley DB includes tools to assist in the development of + application-specific logging and recovery. Specifically, given + a description of information to be logged in a family of log + records, these tools will automatically create log-writing + functions (functions that marshall their arguments into a + single log record), log-reading functions (functions that read + a log record and unmarshall it into a structure containing + fields that map into the arguments written to the log), + log-printing functions (functions that print the contents of a + log record for debugging), and templates for recovery + functions (functions that review log records during + transaction abort or recovery). The tools and generated code + are C-language and POSIX-system based, but the generated code + should be usable on any system, not just POSIX systems. + </p> + <p> + A sample application that does application-specific recovery + is included in the Berkeley DB distribution, in the directory + <code class="filename">examples/c/ex_apprec</code>. + </p> </div> </div> <div class="navfooter"> @@ -149,7 +179,8 @@ in the Berkeley DB distribution, in the directory <code class="filename">example <td width="20%" align="center"> <a accesskey="h" href="index.html">Home</a> </td> - <td width="40%" align="right" valign="top"> Defining application-specific log records</td> + <td width="40%" align="right" valign="top"> Defining application-specific log + records</td> </tr> </table> </div> |