Sindbad~EG File Manager
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Chapter 15. Application Specific Logging and Recovery</title>
<link rel="stylesheet" href="gettingStarted.css" type="text/css" />
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
<link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
<link rel="up" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
<link rel="prev" href="xa_faq.html" title="XA: Frequently Asked Questions" />
<link rel="next" href="apprec_def.html" title="Defining application-specific log records" />
</head>
<body>
<div xmlns="" class="navheader">
<div class="libver">
<p>Library Version 18.1.40</p>
</div>
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">Chapter 15. Application Specific Logging and
Recovery </th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="xa_faq.html">Prev</a> </td>
<th width="60%" align="center"> </th>
<td width="20%" align="right"> <a accesskey="n" href="apprec_def.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="chapter" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title"><a id="apprec"></a>Chapter 15. Application Specific Logging and
Recovery </h2>
</div>
</div>
</div>
<div class="toc">
<p>
<b>Table of Contents</b>
</p>
<dl>
<dt>
<span class="sect1">
<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>
</span>
</dt>
<dt>
<span class="sect1">
<a href="apprec_auto.html">Automatically generated
functions</a>
</span>
</dt>
<dt>
<span class="sect1">
<a href="apprec_config.html">Application configuration</a>
</span>
</dt>
</dl>
</div>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<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>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="xa_faq.html">Prev</a> </td>
<td width="20%" align="center"> </td>
<td width="40%" align="right"> <a accesskey="n" href="apprec_def.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">XA: Frequently Asked Questions </td>
<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>
</tr>
</table>
</div>
</body>
</html>
Sindbad File Manager Version 1.0, Coded By Sindbad EG ~ The Terrorists