1<!--$Id: fail.so,v 10.2 2005/10/19 21:10:31 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: Handling failure in Transactional Data Store applications</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>Berkeley DB Transactional Data Store Applications</dl></b></td> 13<td align=right><a href="../transapp/term.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../transapp/app.html"><img src="../../images/next.gif" alt="Next"></a> 14</td></tr></table> 15<p align=center><b>Handling failure in Transactional Data Store applications</b></p> 16<p>When building Transactional Data Store applications, there are design 17issues to consider whenever a thread of control with open Berkeley DB handles 18fails for any reason (where a thread of control may be either a true 19thread or a process).</p> 20<p>The first case is handling system failure: if the system fails, the 21database environment and the databases may be left in a corrupted state. 22In this case, recovery must be performed on the database environment 23before any further action is taken, in order to:</p> 24<p><ul type=disc> 25<li>recover the database environment resources, 26<li>release any locks or mutexes that may have been held to avoid starvation 27as the remaining threads of control convoy behind the held locks, and 28<li>resolve any partially completed operations that may have left a database 29in an inconsistent or corrupted state. 30</ul> 31<p>For details on performing recovery, see the <a href="recovery.html">Recovery 32procedures</a>.</p> 33<p>The second case is handling the failure of a thread of control. There 34are resources maintained in database environments that may be left 35locked or corrupted if a thread of control exits unexpectedly. These 36resources include data structure mutexes, logical database locks and 37unresolved transactions (that is, transactions which were never aborted 38or committed). While Transactional Data Store applications can treat 39the failure of a thread of control in the same way as they do a system 40failure, they have an alternative choice, the <a href="../../api_c/env_failchk.html">DB_ENV->failchk</a> method.</p> 41<p>The <a href="../../api_c/env_failchk.html">DB_ENV->failchk</a> method will return <a href="../../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a> if the 42database environment is unusable as a result of the thread of control 43failure. (If a data structure mutex or a database write lock is left 44held by thread of control failure, the application should not continue 45to use the database environment, as subsequent use of the environment 46is likely to result in threads of control convoying behind the held 47locks.) The <a href="../../api_c/env_failchk.html">DB_ENV->failchk</a> call will release any database read 48locks that have been left held by the exit of a thread of control, and 49abort any unresolved transactions. In this case, the application can 50continue to use the database environment.</p> 51<p>A Transactional Data Store application recovering from a thread of 52control failure should call <a href="../../api_c/env_failchk.html">DB_ENV->failchk</a>, and, if it returns 53success, the application can continue. If <a href="../../api_c/env_failchk.html">DB_ENV->failchk</a> returns 54<a href="../../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a>, the application should proceed as described for 55the case of system failure.</p> 56<p>It greatly simplifies matters that recovery may be performed regardless 57of whether recovery needs to be performed; that is, it is not an error 58to recover a database environment for which recovery is not strictly 59necessary. For this reason, applications should not try to determine 60if the database environment was active when the application or system 61failed. Instead, applications should run recovery any time the 62<a href="../../api_c/env_failchk.html">DB_ENV->failchk</a> method returns <a href="../../ref/program/errorret.html#DB_RUNRECOVERY">DB_RUNRECOVERY</a>, or, if the 63application is not calling <a href="../../api_c/env_failchk.html">DB_ENV->failchk</a> method, any time any thread 64of control accessing the database environment fails, as well as any time 65the system reboots.</p> 66<table width="100%"><tr><td><br></td><td align=right><a href="../transapp/term.html"><img src="../../images/prev.gif" alt="Prev"></a><a href="../toc.html"><img src="../../images/ref.gif" alt="Ref"></a><a href="../transapp/app.html"><img src="../../images/next.gif" alt="Next"></a> 67</td></tr></table> 68<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 69</body> 70</html> 71