1<?xml version="1.0" encoding="UTF-8" standalone="no"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml"> 4 <head> 5 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 6 <title>Handling failure in Transactional Data Store applications</title> 7 <link rel="stylesheet" href="gettingStarted.css" type="text/css" /> 8 <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> 9 <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" /> 10 <link rel="up" href="transapp.html" title="Chapter 11. Berkeley DB Transactional Data Store Applications" /> 11 <link rel="prev" href="transapp_term.html" title="Terminology" /> 12 <link rel="next" href="transapp_app.html" title="Architecting Transactional Data Store applications" /> 13 </head> 14 <body> 15 <div class="navheader"> 16 <table width="100%" summary="Navigation header"> 17 <tr> 18 <th colspan="3" align="center">Handling failure in Transactional Data Store applications</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="transapp_term.html">Prev</a> </td> 22 <th width="60%" align="center">Chapter 11. 23 Berkeley DB Transactional Data Store Applications 24 </th> 25 <td width="20%" align="right"> <a accesskey="n" href="transapp_app.html">Next</a></td> 26 </tr> 27 </table> 28 <hr /> 29 </div> 30 <div class="sect1" lang="en" xml:lang="en"> 31 <div class="titlepage"> 32 <div> 33 <div> 34 <h2 class="title" style="clear: both"><a id="transapp_fail"></a>Handling failure in Transactional Data Store applications</h2> 35 </div> 36 </div> 37 </div> 38 <p> 39 When building Transactional Data Store applications, there are design 40 issues to consider whenever a thread of control with open Berkeley DB 41 handles fails for any reason (where a thread of control may be either a 42 true thread or a process). 43</p> 44 <p> 45 The first case is handling system failure: if the system fails, the 46 database environment and the databases may be left in a corrupted 47 state. In this case, recovery must be performed on the database 48 environment before any further action is taken, in order to: 49</p> 50 <div class="itemizedlist"> 51 <ul type="disc"> 52 <li>recover the database environment resources,</li> 53 <li>release any locks or mutexes that may have been held to avoid starvation 54as the remaining threads of control convoy behind the held locks, and</li> 55 <li>resolve any partially completed operations that may have left a database 56in an inconsistent or corrupted state.</li> 57 </ul> 58 </div> 59 <p> 60 For details on performing recovery, see the 61 <a class="xref" href="transapp_recovery.html" title="Recovery procedures">Recovery procedures</a>. 62</p> 63 <p> 64 The second case is handling the failure of a thread of control. There 65 are resources maintained in database environments that may be left 66 locked or corrupted if a thread of control exits unexpectedly. These 67 resources include data structure mutexes, logical database locks and 68 unresolved transactions (that is, transactions which were never aborted 69 or committed). While Transactional Data Store applications can treat 70 the failure of a thread of control in the same way as they do a system 71 failure, they have an alternative choice, the <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> method. 72</p> 73 <p> 74 The <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> will return 75 <a class="link" href="program_errorret.html#program_errorret.DB_RUNRECOVERY">DB_RUNRECOVERY</a> 76 if the database 77 environment is unusable as a result of the thread of control failure. 78 (If a data structure mutex or a database write lock is left held by 79 thread of control failure, the application should not continue to use 80 the database environment, as subsequent use of the environment is 81 likely to result in threads of control convoying behind the held 82 locks.) The <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> call will release any database read locks 83 that have been left held by the exit of a thread of control, and abort 84 any unresolved transactions. In this case, the application can 85 continue to use the database environment. 86</p> 87 <p> 88 A Transactional Data Store application recovering from a thread of 89 control failure should call <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a>, and, if it returns success, 90 the application can continue. If <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> returns 91 <a class="link" href="program_errorret.html#program_errorret.DB_RUNRECOVERY">DB_RUNRECOVERY</a>, 92 the application should proceed as described for 93 the case of system failure. 94</p> 95 <p> 96 It greatly simplifies matters that recovery may be performed regardless 97 of whether recovery needs to be performed; that is, it is not an error 98 to recover a database environment for which recovery is not strictly 99 necessary. For this reason, applications should not try to determine 100 if the database environment was active when the application or system 101 failed. Instead, applications should run recovery any time the 102 <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> method returns 103 <a class="link" href="program_errorret.html#program_errorret.DB_RUNRECOVERY">DB_RUNRECOVERY</a>, 104 or, if the application is 105 not calling the <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> method, any time any thread of control 106 accessing the database environment fails, as well as any time the 107 system reboots. 108</p> 109 </div> 110 <div class="navfooter"> 111 <hr /> 112 <table width="100%" summary="Navigation footer"> 113 <tr> 114 <td width="40%" align="left"><a accesskey="p" href="transapp_term.html">Prev</a> </td> 115 <td width="20%" align="center"> 116 <a accesskey="u" href="transapp.html">Up</a> 117 </td> 118 <td width="40%" align="right"> <a accesskey="n" href="transapp_app.html">Next</a></td> 119 </tr> 120 <tr> 121 <td width="40%" align="left" valign="top">Terminology </td> 122 <td width="20%" align="center"> 123 <a accesskey="h" href="index.html">Home</a> 124 </td> 125 <td width="40%" align="right" valign="top"> Architecting Transactional Data Store applications</td> 126 </tr> 127 </table> 128 </div> 129 </body> 130</html> 131