1<!--$Id: intro.so,v 10.53 2006/11/13 18:04:59 bostic Exp $-->
2<!--Copyright (c) 1997,2008 Oracle.  All rights reserved.-->
3<!--See the file LICENSE for redistribution information.-->
4<html>
5<head>
6<title>Berkeley DB Reference Guide: Introduction to application specific logging and recovery</title>
7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
9</head>
10<body bgcolor=white>
11<table width="100%"><tr valign=top>
12<td><b><dl><dt>Berkeley DB Reference Guide:<dd>Application Specific Logging and Recovery</dl></b></td>
13<td align=right><a href="/xa/faq.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/apprec/def.html"><img src="/images/next.gif" alt="Next"></a>
14</td></tr></table>
15<p align=center><b>Introduction to application specific logging and recovery</b></p>
16<p>It is possible to use the Locking, Logging and Transaction subsystems
17of Berkeley DB to provide transaction semantics on objects other than those
18described by the Berkeley DB access methods.  In these cases, the application
19will need application-specific logging and recovery functions.</p>
20<p>For example, consider an application that provides transaction semantics
21on data stored in plain text files accessed using the POSIX read and
22write system calls.  The read and write operations for which transaction
23protection is desired will be bracketed by calls to the standard Berkeley DB
24transactional interfaces, <a href="/api_c/txn_begin.html">DB_ENV-&gt;txn_begin</a> and <a href="/api_c/txn_commit.html">DB_TXN-&gt;commit</a>, and
25the transaction's locker ID will be used to acquire relevant read and
26write locks.</p>
27<p>Before data is accessed, the application must make a call to the lock
28manager, <a href="/api_c/lock_get.html">DB_ENV-&gt;lock_get</a>, for a lock of the appropriate type (for
29example, read) on the object being locked.  The object might be a page
30in the file, a byte, a range of bytes, or some key.  It is up to the
31application to ensure that appropriate locks are acquired.  Before a
32write is performed, the application should acquire a write lock on the
33object by making an appropriate call to the lock manager,
34<a href="/api_c/lock_get.html">DB_ENV-&gt;lock_get</a>.  Then, the application should make a call to the log
35manager, via the automatically-generated log-writing function described
36as follows.  This record should contain enough information to redo the
37operation in case of failure after commit and to undo the operation in
38case of abort.</p>
39<p>When designing applications that will use the log subsystem, it is
40important to remember that the application is responsible for providing
41any necessary structure to the log record.  For example, the application
42must understand what part of the log record is an operation code, what
43part identifies the file being modified, what part is redo information,
44and what part is undo information.</p>
45<p>After the log message is written, the application may issue the write
46system call.  After all requests are issued, the application may call
47<a href="/api_c/txn_commit.html">DB_TXN-&gt;commit</a>.  When <a href="/api_c/txn_commit.html">DB_TXN-&gt;commit</a> returns, the caller is
48guaranteed that all necessary log writes have been written to disk.</p>
49<p>At any time before issuing a <a href="/api_c/txn_commit.html">DB_TXN-&gt;commit</a>, the application may
50call <a href="/api_c/txn_abort.html">DB_TXN-&gt;abort</a>, which will result in restoration of the database
51to a consistent pretransaction state.  (The application may specify its
52own recovery function for this purpose using the
53<a href="/api_c/env_set_app_dispatch.html">DB_ENV-&gt;set_app_dispatch</a> method.  The recovery function must be able to
54either reapply or undo the update depending on the context, for each
55different type of log record. The recovery functions must not use Berkeley DB
56methods to access data in the environment as there is no way to
57coordinate these accesses with either the aborting transaction or the
58updates done by recovery or replication.)</p>
59<p>If the application crashes, the recovery process uses the log to restore
60the database to a consistent state.</p>
61<p>Berkeley DB includes tools to assist in the development of application-specific
62logging and recovery.  Specifically, given a description of information
63to be logged in a family of log records, these tools will automatically
64create log-writing functions (functions that marshall their arguments
65into a single log record), log-reading functions (functions that read
66a log record and unmarshall it into a structure containing fields that
67map into the arguments written to the log), log-printing functions
68(functions that print the contents of a log record for debugging), and
69templates for recovery functions (functions that review log records
70during transaction abort or recovery).  The tools and generated code
71are C-language and POSIX-system based, but the generated code should be
72usable on any system, not just POSIX systems.</p>
73<p>A sample application that does application-specific recovery is included
74in the Berkeley DB distribution, in the directory <b>examples_c/ex_apprec</b>.</p>
75<table width="100%"><tr><td><br></td><td align=right><a href="/xa/faq.html"><img src="/images/prev.gif" alt="Prev"></a><a href="/toc.html"><img src="/images/ref.gif" alt="Ref"></a><a href="/apprec/def.html"><img src="/images/next.gif" alt="Next"></a>
76</td></tr></table>
77<p><font size=1>Copyright (c) 1996,2008 Oracle.  All rights reserved.</font>
78</body>
79</html>
80