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 Data Store and Concurrent 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="cam.html" title="Chapter��10.�� Berkeley DB Concurrent Data Store Applications" /> 11 <link rel="prev" href="cam.html" title="Chapter��10.�� Berkeley DB Concurrent Data Store Applications" /> 12 <link rel="next" href="cam_app.html" title="Architecting Data Store and Concurrent 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 Data Store and Concurrent Data Store applications</th> 19 </tr> 20 <tr> 21 <td width="20%" align="left"><a accesskey="p" href="cam.html">Prev</a>��</td> 22 <th width="60%" align="center">Chapter��10.�� 23 Berkeley DB Concurrent Data Store Applications 24 </th> 25 <td width="20%" align="right">��<a accesskey="n" href="cam_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="cam_fail"></a>Handling failure in Data Store and Concurrent Data Store applications</h2> 35 </div> 36 </div> 37 </div> 38 <p>When building Data Store and Concurrent Data Store applications, there 39are design issues to consider whenever a thread of control with open 40Berkeley DB handles fails for any reason (where a thread of control may be 41either a true thread or a process).</p> 42 <p>The simplest case is handling system failure for any Data Store or 43Concurrent Data Store application. In the case of system failure, it 44doesn't matter if the application has opened a database environment or 45is just using standalone databases: if the system fails, after the 46application has modified a database and has not subsequently flushed the 47database to stable storage (by calling either the <a href="../api_reference/C/dbclose.html" class="olink">DB->close()</a>, 48<a href="../api_reference/C/dbsync.html" class="olink">DB->sync()</a> or <a href="../api_reference/C/mempsync.html" class="olink">DB_ENV->memp_sync()</a> methods), the database may be left in a 49corrupted state. In this case, before accessing the database again, the 50database should either be:</p> 51 <div class="itemizedlist"> 52 <ul type="disc"> 53 <li>removed and re-created,</li> 54 <li>removed and restored from the last known good backup, or</li> 55 <li>verified using the <a href="../api_reference/C/dbverify.html" class="olink">DB->verify()</a> method or <a href="../api_reference/C/db_verify.html" class="olink">db_verify utility</a> utility. If 56the database does not verify cleanly, the contents may be salvaged using 57the <span class="bold"><strong>-R</strong></span> and <span class="bold"><strong>-r</strong></span> options of the <a href="../api_reference/C/db_dump.html" class="olink">db_dump utility</a>.</li> 58 </ul> 59 </div> 60 <p>Applications where the potential for data loss is unacceptable should 61consider the Berkeley DB Transactional Data Store product, which offers standard transactional 62durability guarantees, including recoverability after failure.</p> 63 <p>Additionally, system failure requires that any persistent database 64environment (that is, any database environment not created using the 65<a href="../api_reference/C/envopen.html#open_DB_PRIVATE" class="olink">DB_PRIVATE</a> flag), be removed. Database environments may be 66removed using the <a href="../api_reference/C/envremove.html" class="olink">DB_ENV->remove()</a> method. If the persistent database 67environment was backed by the filesystem (that is, the environment was 68not created using the <a href="../api_reference/C/envopen.html#envopen_DB_SYSTEM_MEM" class="olink">DB_SYSTEM_MEM</a> flag), the database 69environment may also be safely removed by deleting the environment's 70files with standard system utilities.</p> 71 <p>The second case is application failure for a Data Store application, 72with or without a database environment, or application failure for a 73Concurrent Data Store application without a database environment: as in 74the case of system failure, if any thread of control fails, after the 75application has modified a database and has not subsequently flushed the 76database to stable storage, the database may be left in a corrupted 77state. In this case, the database should be handled as described 78previously in the system failure case.</p> 79 <p>The third case is application failure for a Concurrent Data Store 80application with a database environment. There are resources maintained 81in database environments that may be left locked if a thread of control 82exits without first closing all open Berkeley DB handles. Concurrent Data 83Store applications with database environments have an additional option 84for handling the unexpected exit of a thread of control, the 85<a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> method.</p> 86 <p>The <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> will return <a class="link" href="program_errorret.html#program_errorret.DB_RUNRECOVERY">DB_RUNRECOVERY</a> if the 87database environment is unusable as a result of the thread of control 88failure. (If a data structure mutex or a database write lock is left 89held by thread of control failure, the application should not continue 90to use the database environment, as subsequent use of the environment 91is likely to result in threads of control convoying behind the held 92locks.) The <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> call will release any database read 93locks that have been left held by the exit of a thread of control. In 94this case, the application can continue to use the database 95environment.</p> 96 <p>A Concurrent Data Store application recovering from a thread of control 97failure should call <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a>, and, if it returns success, 98the application can continue. If <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> returns 99<a class="link" href="program_errorret.html#program_errorret.DB_RUNRECOVERY">DB_RUNRECOVERY</a>, the application should proceed as described for 100the case of system failure.</p> 101 </div> 102 <div class="navfooter"> 103 <hr /> 104 <table width="100%" summary="Navigation footer"> 105 <tr> 106 <td width="40%" align="left"><a accesskey="p" href="cam.html">Prev</a>��</td> 107 <td width="20%" align="center"> 108 <a accesskey="u" href="cam.html">Up</a> 109 </td> 110 <td width="40%" align="right">��<a accesskey="n" href="cam_app.html">Next</a></td> 111 </tr> 112 <tr> 113 <td width="40%" align="left" valign="top">Chapter��10.�� 114 Berkeley DB Concurrent Data Store Applications 115 ��</td> 116 <td width="20%" align="center"> 117 <a accesskey="h" href="index.html">Home</a> 118 </td> 119 <td width="40%" align="right" valign="top">��Architecting Data Store and Concurrent Data Store applications</td> 120 </tr> 121 </table> 122 </div> 123 </body> 124</html> 125