diff options
Diffstat (limited to 'docs/programmer_reference/transapp_fail.html')
| -rw-r--r-- | docs/programmer_reference/transapp_fail.html | 159 |
1 files changed, 91 insertions, 68 deletions
diff --git a/docs/programmer_reference/transapp_fail.html b/docs/programmer_reference/transapp_fail.html index 1ac9442f..f58cfb20 100644 --- a/docs/programmer_reference/transapp_fail.html +++ b/docs/programmer_reference/transapp_fail.html @@ -14,7 +14,7 @@ <body> <div xmlns="" class="navheader"> <div class="libver"> - <p>Library Version 11.2.5.3</p> + <p>Library Version 12.1.6.1</p> </div> <table width="100%" summary="Navigation header"> <tr> @@ -22,9 +22,7 @@ </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="transapp_term.html">Prev</a> </td> - <th width="60%" align="center">Chapter 11. - Berkeley DB Transactional Data Store Applications - </th> + <th width="60%" align="center">Chapter 11. Berkeley DB Transactional Data Store Applications </th> <td width="20%" align="right"> <a accesskey="n" href="transapp_app.html">Next</a></td> </tr> </table> @@ -38,77 +36,101 @@ </div> </div> </div> - <p> - When building Transactional Data Store applications, there are design - issues to consider whenever a thread of control with open Berkeley DB - handles fails for any reason (where a thread of control may be either a - true thread or a process). -</p> - <p> - The first case is handling system failure: if the system fails, the - database environment and the databases may be left in a corrupted - state. In this case, recovery must be performed on the database - environment before any further action is taken, in order to: -</p> + <p> + When building Transactional Data Store applications, there + are design issues to consider whenever a thread of control + with open Berkeley DB handles fails for any reason (where a + thread of control may be either a true thread or a process). + </p> + <p> + The first case is handling system failure: if the system + fails, the database environment and the databases may be left + in a corrupted state. In this case, recovery must be performed + on the database environment before any further action is + taken, in order to: + </p> <div class="itemizedlist"> <ul type="disc"> - <li>recover the database environment resources,</li> - <li>release any locks or mutexes that may have been held to avoid starvation -as the remaining threads of control convoy behind the held locks, and</li> - <li>resolve any partially completed operations that may have left a database -in an inconsistent or corrupted state.</li> + <li> + recover the database environment + resources, + </li> + <li> + release any locks or mutexes that may have been held + to avoid starvation as the remaining threads of control + convoy behind the held locks, and + </li> + <li> + resolve any partially completed operations that may + have left a database in an inconsistent or corrupted + state. + </li> </ul> </div> <p> - For details on performing recovery, see the - <a class="xref" href="transapp_recovery.html" title="Recovery procedures">Recovery procedures</a>. -</p> - <p> - The second case is handling the failure of a thread of control. There - are resources maintained in database environments that may be left - locked or corrupted if a thread of control exits unexpectedly. These - resources include data structure mutexes, logical database locks and - unresolved transactions (that is, transactions which were never aborted - or committed). While Transactional Data Store applications can treat - the failure of a thread of control in the same way as they do a system - failure, they have an alternative choice, the <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> method. -</p> + For details on performing recovery, see the <a class="xref" href="transapp_recovery.html" title="Recovery procedures">Recovery procedures</a>. + </p> <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 database - environment is unusable as a result of the thread of control failure. - (If a data structure mutex or a database write lock is left held by - thread of control failure, the application should not continue to use - the database environment, as subsequent use of the environment is - likely to result in threads of control convoying behind the held - locks.) The <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> call will release any database read locks - that have been left held by the exit of a thread of control, and abort - any unresolved transactions. In this case, the application can - continue to use the database environment. -</p> + The second case is handling the failure of a thread of + control. There are resources maintained in database + environments that may be left locked or corrupted if a thread + of control exits unexpectedly. These resources include data + structure mutexes, logical database locks and unresolved + transactions (that is, transactions which were never aborted + or committed). While Transactional Data Store applications can + treat the failure of a thread of control in the same way as + they do a system failure, they have an alternative choice, the + <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> method. + </p> + <p> + The <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> method will return + <a class="link" href="program_errorret.html#program_errorret.DB_RUNRECOVERY">DB_RUNRECOVERY</a> + if the database environment is unusable as a result of the thread + of control failure. (If a data structure mutex or a database write + lock is left held by thread of control failure, the application + should not continue to use the database environment, as subsequent + use of the environment is likely to result in threads of control + convoying behind the held locks.) The <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> call will + release any database read locks that have been left held by the + exit of a thread of control, and abort any unresolved transactions. + In this case, the application can continue to use the database + environment. + </p> <p> - A Transactional Data Store application recovering from a thread of - control failure should call <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a>, and, if it returns success, - the application can continue. If <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> returns - <a class="link" href="program_errorret.html#program_errorret.DB_RUNRECOVERY">DB_RUNRECOVERY</a>, - the application should proceed as described for - the case of system failure. -</p> + Note that you can optionally cause <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> to broadcast a database + environment failure to other threads of control by using the + <code class="literal">--enable-failchk_broadcast</code> flag when you compile + your Berkeley DB library. If this option is turned on, then all + threads of control using the database environment will return + <a class="link" href="program_errorret.html#program_errorret.DB_RUNRECOVERY">DB_RUNRECOVERY</a> + when they attempt to obtain a mutex lock. In this situation, a + <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_FAILCHK_PANIC" class="olink">DB_EVENT_FAILCHK_PANIC</a> or + <a href="../api_reference/C/envevent_notify.html#event_notify_DB_EVENT_MUTEX_DIED" class="olink">DB_EVENT_MUTEX_DIED</a> event will also be raised. + (You use <a href="../api_reference/C/envevent_notify.html" class="olink">DB_ENV->set_event_notify()</a> to examine events). + </p> + <p> + A Transactional Data Store application recovering from a + thread of control failure should call <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a>, and, if it + returns success, the application can continue. If <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> + returns <a class="link" href="program_errorret.html#program_errorret.DB_RUNRECOVERY">DB_RUNRECOVERY</a>, + the application should proceed as described for the case of system + failure. In addition, threads notified of failure by <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> + should also proceed as described for the case of system failure. + </p> <p> - It greatly simplifies matters that recovery may be performed regardless - of whether recovery needs to be performed; that is, it is not an error - to recover a database environment for which recovery is not strictly - necessary. For this reason, applications should not try to determine - if the database environment was active when the application or system - failed. Instead, applications should run recovery any time the - <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> method returns - <a class="link" href="program_errorret.html#program_errorret.DB_RUNRECOVERY">DB_RUNRECOVERY</a>, - or, if the application is - not calling the <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> method, any time any thread of control - accessing the database environment fails, as well as any time the - system reboots. -</p> + It greatly simplifies matters that recovery may be + performed regardless of whether recovery needs to be + performed; that is, it is not an error to recover a database + environment for which recovery is not strictly necessary. For + this reason, applications should not try to determine if the + database environment was active when the application or system + failed. Instead, applications should run recovery any time the + <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> method returns <a class="link" href="program_errorret.html#program_errorret.DB_RUNRECOVERY"> + DB_RUNRECOVERY</a>, or, if the application is not + calling the <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> method, any time any thread of + control accessing the database environment fails, as well as + any time the system reboots. + </p> </div> <div class="navfooter"> <hr /> @@ -125,7 +147,8 @@ in an inconsistent or corrupted state.</li> <td width="20%" align="center"> <a accesskey="h" href="index.html">Home</a> </td> - <td width="40%" align="right" valign="top"> Architecting Transactional Data Store applications</td> + <td width="40%" align="right" valign="top"> Architecting Transactional Data + Store applications</td> </tr> </table> </div> |