mirror of
https://github.com/yasuhirokimura/db18
synced 2026-06-08 18:29:23 +00:00
Yasuhiro KIMURA
189 lines
8.8 KiB
HTML
189 lines
8.8 KiB
HTML
<?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>
|