← Back to branch summary

~ubuntu-branches/ubuntu/precise/rpm/precise-proposed

« back to all changes in this revision

Viewing changes to db/docs/ref/apprec/config.html

  • Committer: Bazaar Package Importer
  • Author(s): Michael Vogt
  • Date: 2009-06-25 18:57:20 UTC
  • mfrom: (1.1.5 upstream) (4.1.2 sid)
  • Revision ID: james.westby@ubuntu.com-20090625185720-617sjskgtgmf09vf
Tags: 4.7.0-7ubuntu1
* Merge from debian unstable, remaining changes:
  - change build depends from libdwarf-dev -> libdw-dev
    (libdwarf-dev is in universe)

Show diffs side-by-side

added added

removed removed

Lines of Context:
db/docs/ref/apprec/config.html
1
 
<!--$Id: config.so,v 10.4 2002/06/05 21:09:14 bostic Exp $-->
2
 
<!--Copyright 1997-2004 by Sleepycat Software, Inc.-->
3
 
<!--All rights reserved.-->
4
 
<!--See the file LICENSE for redistribution information.-->
5
 
<html>
6
 
<head>
7
 
<title>Berkeley DB Reference Guide: Application configuration</title>
8
 
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
9
 
<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
10
 
</head>
11
 
<body bgcolor=white>
12
 
<table width="100%"><tr valign=top>
13
 
<td><h3><dl><dt>Berkeley DB Reference Guide:<dd>Application Specific Logging and Recovery</dl></h3></td>
14
 
<td align=right><a href="../apprec/auto.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../program/appsignals.html"><img src="../../images/next.gif" alt="Next"></a>
15
 
</td></tr></table>
16
 
<p>
17
 
<h3 align=center>Application configuration</h3>
18
 
<p>The application should include a dispatch function that dispatches to
19
 
appropriate printing and/or recovery functions based on the log record
20
 
type and the operation code.  The dispatch function should take the same
21
 
arguments as the recovery function, and should call the appropriate
22
 
recovery and/or printing functions based on the log record type and the
23
 
operation code.  For example, the ex_apprec dispatch function is as
24
 
follows:</p>
25
 
<blockquote><pre>int
26
 
apprec_dispatch(dbenv, dbt, lsn, op)
27
 
        DB_ENV *dbenv;
28
 
        DBT *dbt;
29
 
        DB_LSN *lsn;
30
 
        db_recops op;
31
 
{
32
 
        u_int32_t rectype;
33
 
        /* Pull the record type out of the log record. */
34
 
        memcpy(&rectype, dbt-&gt;data, sizeof(rectype));
35
 
        switch (rectype) {
36
 
        case DB_ex_apprec_mkdir:
37
 
                return (ex_apprec_mkdir_recover(dbenv, dbt, lsn, op, NULL));
38
 
        default:
39
 
                /*
40
 
                 * We've hit an unexpected, allegedly user-defined record
41
 
                 * type.
42
 
                 */
43
 
                dbenv-&gt;errx(dbenv, "Unexpected log record type encountered");
44
 
                return (EINVAL);
45
 
        }
46
 
}
47
 
</pre></blockquote>
48
 
<p>Applications use this dispatch function and the automatically generated
49
 
functions as follows:</p>
50
 
<ol>
51
 
<p><li>When the application starts, call the <a href="../../api_c/env_set_app_dispatch.html">DB_ENV-&gt;set_app_dispatch</a>
52
 
with your dispatch function.
53
 
<p><li>Issue a <a href="../../api_c/txn_begin.html">DB_ENV-&gt;txn_begin</a> call before any operations you want to be
54
 
transaction-protected.
55
 
<p><li>Before accessing any data, issue the appropriate lock call to lock the
56
 
data (either for reading or writing).
57
 
<p><li>Before modifying any data that is transaction-protected, issue a call
58
 
to the appropriate log function.
59
 
<p><li>Call <a href="../../api_c/txn_commit.html">DB_TXN-&gt;commit</a> to save all the changes, or call <a href="../../api_c/txn_abort.html">DB_TXN-&gt;abort</a>
60
 
to cancel all of the modifications.
61
 
</ol>
62
 
<p>The recovery functions are called in the three following cases:</p>
63
 
<ol>
64
 
<p><li>During recovery after application or system failure, with op set to
65
 
<a href="../../api_c/env_set_app_dispatch.html#DB_TXN_FORWARD_ROLL">DB_TXN_FORWARD_ROLL</a> or <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_BACKWARD_ROLL">DB_TXN_BACKWARD_ROLL</a>.
66
 
<p><li>During transaction abort, with op set to <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_ABORT">DB_TXN_ABORT</a>.
67
 
<p><li>On a replicated client to apply updates from the master, with op set to
68
 
<a href="../../api_c/env_set_app_dispatch.html#DB_TXN_APPLY">DB_TXN_APPLY</a>.
69
 
</ol>
70
 
<p>For each log record type you declare, you must write the appropriate
71
 
function to undo and redo the modifications.  The shell of these
72
 
functions will be generated for you automatically, but you must fill in
73
 
the details.</p>
74
 
<p>Your code must be able to detect whether the described modifications
75
 
have been applied to the data.  The function will be called with the
76
 
"op" parameter set to <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_ABORT">DB_TXN_ABORT</a> when a transaction that wrote
77
 
the log record aborts, with <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_FORWARD_ROLL">DB_TXN_FORWARD_ROLL</a> and
78
 
<a href="../../api_c/env_set_app_dispatch.html#DB_TXN_BACKWARD_ROLL">DB_TXN_BACKWARD_ROLL</a> during recovery, and with <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_APPLY">DB_TXN_APPLY</a>
79
 
on a replicated client.</p>
80
 
<p>The actions for <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_ABORT">DB_TXN_ABORT</a> and <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_BACKWARD_ROLL">DB_TXN_BACKWARD_ROLL</a>
81
 
should generally be the same, and the actions for
82
 
<a href="../../api_c/env_set_app_dispatch.html#DB_TXN_FORWARD_ROLL">DB_TXN_FORWARD_ROLL</a> and <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_APPLY">DB_TXN_APPLY</a> should generally
83
 
be the same.  However, if the application is using Berkeley DB replication
84
 
and another thread of control may be performing read operations while
85
 
log records are applied on a replication client, the recovery function
86
 
should perform appropriate locking during <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_APPLY">DB_TXN_APPLY</a>
87
 
operations.  In this case, the recovery function may encounter deadlocks
88
 
when issuing locking calls.  The application should run with the
89
 
deadlock detector, and the recovery function should simply return
90
 
<a href="../../ref/program/errorret.html#DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a> if a deadlock is detected and a locking
91
 
operation fails with that error.</p>
92
 
<p>The <a href="../../api_c/env_set_app_dispatch.html#DB_TXN_PRINT">DB_TXN_PRINT</a> operation should print the log record,
93
 
typically using the auto-generated print function; it is not used in
94
 
the Berkeley DB library, but may be useful for debugging, as in the
95
 
<a href="../../utility/db_printlog.html">db_printlog</a> utility.  Applications may safely ignore this
96
 
operation code, they may handle printing from the recovery function, or
97
 
they may dispatch directly to the auto-generated print function.</p>
98
 
<p>One common way to determine whether operations need to be undone or
99
 
redone is the use of log sequence numbers (LSNs).  For example, each
100
 
access method database page contains the LSN of the most recent log
101
 
record that describes a modification to the page.  When the access
102
 
method changes a page, it writes a log record describing the change and
103
 
including the LSN that was on the page before the change.  This LSN is
104
 
referred to as the previous LSN.  The recovery functions read the page
105
 
described by a log record, and compare the LSN on the page to the LSN
106
 
they were passed.</p>
107
 
<p>If the page LSN is less than the passed LSN and the operation is an
108
 
undo, no action is necessary (because the modifications have not been
109
 
written to the page).  If the page LSN is the same as the previous LSN
110
 
and the operation is a redo, the actions described are reapplied to the
111
 
page.  If the page LSN is equal to the passed LSN and the operation is
112
 
an undo, the actions are removed from the page; if the page LSN is
113
 
greater than the passed LSN and the operation is a redo, no further
114
 
action is necessary.  If the action is a redo and the LSN on the page
115
 
is less than the previous LSN in the log record, it is an error because
116
 
it could happen only if some previous log record was not processed.</p>
117
 
<p>Examples of other recovery functions can be found in the Berkeley DB library
118
 
recovery functions (found in files named XXX_rec.c) and in the
119
 
application-specific recovery example (specifically, ex_apprec_rec.c).</p>
120
 
<p>Finally, applications need to ensure that any data modifications they
121
 
have made, that were part of a committed transaction, must be written
122
 
to stable storage before calling the <a href="../../api_c/txn_checkpoint.html">DB_ENV-&gt;txn_checkpoint</a> method.  This is
123
 
to allow the periodic removal of database environment log files.</p>
124
 
<table width="100%"><tr><td><br></td><td align=right><a href="../apprec/auto.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../program/appsignals.html"><img src="../../images/next.gif" alt="Next"></a>
125
 
</td></tr></table>
126
 
<p><font size=1><a href="../../sleepycat/legal.html">Copyright (c) 1996-2004</a> <a href="http://www.sleepycat.com">Sleepycat Software, Inc.</a> - All rights reserved.</font>
127
 
</body>
128
 
</html>