diff options
| author | Lorry Tar Creator <lorry-tar-importer@baserock.org> | 2015-02-17 17:25:57 +0000 |
|---|---|---|
| committer | <> | 2015-03-17 16:26:24 +0000 |
| commit | 780b92ada9afcf1d58085a83a0b9e6bc982203d1 (patch) | |
| tree | 598f8b9fa431b228d29897e798de4ac0c1d3d970 /docs/programmer_reference/cam_fail.html | |
| parent | 7a2660ba9cc2dc03a69ddfcfd95369395cc87444 (diff) | |
| download | berkeleydb-master.tar.gz | |
Diffstat (limited to 'docs/programmer_reference/cam_fail.html')
| -rw-r--r-- | docs/programmer_reference/cam_fail.html | 178 |
1 files changed, 112 insertions, 66 deletions
diff --git a/docs/programmer_reference/cam_fail.html b/docs/programmer_reference/cam_fail.html index f638350d..f5669dea 100644 --- a/docs/programmer_reference/cam_fail.html +++ b/docs/programmer_reference/cam_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,8 @@ </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="cam.html">Prev</a> </td> - <th width="60%" align="center">Chapter 10. - Berkeley DB Concurrent Data Store Applications - </th> + <th width="60%" align="center">Chapter 10. Berkeley DB Concurrent Data Store + Applications </th> <td width="20%" align="right"> <a accesskey="n" href="cam_app.html">Next</a></td> </tr> </table> @@ -38,69 +37,117 @@ </div> </div> </div> - <p>When building Data Store and Concurrent 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 simplest case is handling system failure for any Data Store or -Concurrent Data Store application. In the case of system failure, it -doesn't matter if the application has opened a database environment or -is just using standalone databases: if the system fails, after the -application has modified a database and has not subsequently flushed the -database to stable storage (by calling either the <a href="../api_reference/C/dbclose.html" class="olink">DB->close()</a>, -<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 -corrupted state. In this case, before accessing the database again, the -database should either be:</p> + <p> + When building Data Store and Concurrent 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 simplest case is handling system failure for any Data + Store or Concurrent Data Store application. In the case of + system failure, it doesn't matter if the application has + opened a database environment or is just using standalone + databases: if the system fails, after the application has + modified a database and has not subsequently flushed the + database to stable storage (by calling either the <a href="../api_reference/C/dbclose.html" class="olink">DB->close()</a>, + <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 + corrupted state. In this case, before accessing the database + again, the database should either be: + </p> <div class="itemizedlist"> <ul type="disc"> - <li>removed and re-created,</li> - <li>removed and restored from the last known good backup, or</li> - <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</a> utility. If -the database does not verify cleanly, the contents may be salvaged using -the <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</a> utility.</li> + <li> + removed and re-created, + </li> + <li> + removed and restored from the last known good + backup, or + </li> + <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</a> utility. + If the database does not verify cleanly, the contents may + be salvaged using the <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</a> utility. + </li> </ul> </div> - <p>Applications where the potential for data loss is unacceptable should -consider the Berkeley DB Transactional Data Store product, which offers standard transactional -durability guarantees, including recoverability after failure.</p> - <p>Additionally, system failure requires that any persistent database -environment (that is, any database environment not created using the -<a href="../api_reference/C/envopen.html#envopen_DB_PRIVATE" class="olink">DB_PRIVATE</a> flag), be removed. Database environments may be -removed using the <a href="../api_reference/C/envremove.html" class="olink">DB_ENV->remove()</a> method. If the persistent database -environment was backed by the filesystem (that is, the environment was -not created using the <a href="../api_reference/C/envopen.html#envopen_DB_SYSTEM_MEM" class="olink">DB_SYSTEM_MEM</a> flag), the database -environment may also be safely removed by deleting the environment's -files with standard system utilities.</p> - <p>The second case is application failure for a Data Store application, -with or without a database environment, or application failure for a -Concurrent Data Store application without a database environment: as in -the case of system failure, if any thread of control fails, after the -application has modified a database and has not subsequently flushed the -database to stable storage, the database may be left in a corrupted -state. In this case, the database should be handled as described -previously in the system failure case.</p> - <p>The third case is application failure for a Concurrent Data Store -application with a database environment. There are resources maintained -in database environments that may be left locked if a thread of control -exits without first closing all open Berkeley DB handles. Concurrent Data -Store applications with database environments have an additional option -for handling the unexpected exit of a thread of control, 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> 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. In -this case, the application can continue to use the database -environment.</p> - <p>A Concurrent 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> + <p> + Applications where the potential for data loss is + unacceptable should consider the Berkeley DB Transactional + Data Store product, which offers standard transactional + durability guarantees, including recoverability after + failure. + </p> + <p> + Additionally, system failure requires that any persistent + database environment (that is, any database environment not + created using the <a href="../api_reference/C/envopen.html#envopen_DB_PRIVATE" class="olink">DB_PRIVATE</a> flag), be removed. Database + environments may be removed using the <a href="../api_reference/C/envremove.html" class="olink">DB_ENV->remove()</a> method. If + the persistent database environment was backed by the + filesystem (that is, the environment was not created using the + <a href="../api_reference/C/envopen.html#envopen_DB_SYSTEM_MEM" class="olink">DB_SYSTEM_MEM</a> flag), the database environment may also be + safely removed by deleting the environment's files with + standard system utilities. + </p> + <p> + The second case is application failure for a Data Store + application, with or without a database environment, or + application failure for a Concurrent Data Store application + without a database environment: as in the case of system + failure, if any thread of control fails, after the application + has modified a database and has not subsequently flushed the + database to stable storage, the database may be left in a + corrupted state. In this case, the database should be handled + as described previously in the system failure case. + </p> + <p> + The third case is application failure for a Concurrent Data + Store application with a database environment. There are + resources maintained in database environments that may be left + locked if a thread of control exits without first closing all + open Berkeley DB handles. Concurrent Data Store applications + with database environments have an additional option for + handling the unexpected exit of a thread of control, 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> 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. In this case, the application + can continue to use the database environment. + </p> + <p> + Note that by default <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> only notifies the calling thread that + the database environment is unusable. You can optionally cause + <a href="../api_reference/C/envfailchk.html" class="olink">DB_ENV->failchk()</a> to broadcast this 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 + <code class="literal">DB_EVENT_FAILCHK_PANIC</code> or <code class="literal">DB_EVENT_MUTEX_DIED</code> + 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 Concurrent 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> </div> <div class="navfooter"> <hr /> @@ -113,9 +160,8 @@ the case of system failure.</p> <td width="40%" align="right"> <a accesskey="n" href="cam_app.html">Next</a></td> </tr> <tr> - <td width="40%" align="left" valign="top">Chapter 10. - Berkeley DB Concurrent Data Store Applications - </td> + <td width="40%" align="left" valign="top">Chapter 10. Berkeley DB Concurrent Data Store + Applications </td> <td width="20%" align="center"> <a accesskey="h" href="index.html">Home</a> </td> |