📄 busy_handler.html

📁 sqlite3源码,适合作为嵌入式（embedded）
💻 HTML
字号:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"><html><head><title>Register A Callback To Handle SQLITE_BUSY Errors</title><style type="text/css">body {    margin: auto;    font-family: "Verdana" "sans-serif";    padding: 8px 1%;}a { color: #45735f }a:visited { color: #734559 }.logo { position:absolute; margin:3px; }.tagline {  float:right;  text-align:right;  font-style:italic;  width:240px;  margin:12px;  margin-top:58px;}.toolbar {  font-variant: small-caps;  text-align: center;  line-height: 1.6em;  margin: 0;  padding:1px 8px;}.toolbar a { color: white; text-decoration: none; padding: 6px 12px; }.toolbar a:visited { color: white; }.toolbar a:hover { color: #80a796; background: white; }.content    { margin: 5%; }.content dt { font-weight:bold; }.content dd { margin-bottom: 25px; margin-left:20%; }.content ul { padding:0px; padding-left: 15px; margin:0px; }/* rounded corners */.se  { background: url(../images/se.png) 100% 100% no-repeat #80a796}.sw  { background: url(../images/sw.png) 0% 100% no-repeat }.ne  { background: url(../images/ne.png) 100% 0% no-repeat }.nw  { background: url(../images/nw.png) 0% 0% no-repeat }</style><meta http-equiv="content-type" content="text/html; charset=UTF-8">  </head><body><div><!-- container div to satisfy validator --><a href="../index.html"><img class="logo" src="../images/SQLite.gif" alt="SQLite Logo" border="0"></a><div><!-- IE hack to prevent disappearing logo--></div><div class="tagline">Small. Fast. Reliable.<br>Choose any three.</div><table width=100% style="clear:both"><tr><td>  <div class="se"><div class="sw"><div class="ne"><div class="nw">  <div class="toolbar">    <a href="../about.html">About</a>    <a href="../sitemap.html">Sitemap</a>    <a href="../docs.html">Documentation</a>    <a href="../download.html">Download</a>    <a href="../copyright.html">License</a>    <a href="../news.html">News</a>    <a href="http://www.sqlite.org/cvstrac/index">Developers</a>    <a href="../support.html">Support</a>  </div></div></div></div></div></td></tr></table>  <a href="intro.html"><h2>SQLite C Interface</h2></a><h2>Register A Callback To Handle SQLITE_BUSY Errors</h2><blockquote><pre>int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*);</pre></blockquote><p>This routine sets a callback function that might be invoked wheneveran attempt is made to open a database table that another threador process has locked.</p><p>If the busy callback is NULL, then <a href="../c3ref/c_abort.html">SQLITE_BUSY</a> or <a href="../c3ref/c_ioerr_access.html">SQLITE_IOERR_BLOCKED</a>is returned immediately upon encountering the lock. If the busy callbackis not NULL, then the callback will be invoked with two arguments.</p><p>The first argument to the handler is a copy of the void* pointer whichis the third argument to sqlite3_busy_handler().  The second argument tothe handler callback is the number of times that the busy handler hasbeen invoked for this locking event.  If thebusy callback returns 0, then no additional attempts are made toaccess the database and <a href="../c3ref/c_abort.html">SQLITE_BUSY</a> or <a href="../c3ref/c_ioerr_access.html">SQLITE_IOERR_BLOCKED</a> is returned.If the callback returns non-zero, then another attemptis made to open the database for reading and the cycle repeats.</p><p>The presence of a busy handler does not guarantee that it will be invokedwhen there is lock contention. If SQLite determines that invoking the busyhandler could result in a deadlock, it will go ahead and return <a href="../c3ref/c_abort.html">SQLITE_BUSY</a>or <a href="../c3ref/c_ioerr_access.html">SQLITE_IOERR_BLOCKED</a> instead of invoking the busy handler.Consider a scenario where one process is holding a read lock thatit is trying to promote to a reserved lock anda second process is holding a reserved lock that it is tryingto promote to an exclusive lock.  The first process cannot proceedbecause it is blocked by the second and the second process cannotproceed because it is blocked by the first.  If both processesinvoke the busy handlers, neither will make any progress.  Therefore,SQLite returns <a href="../c3ref/c_abort.html">SQLITE_BUSY</a> for the first process, hoping that thiswill induce the first process to release its read lock and allowthe second process to proceed.</p><p>The default busy callback is NULL.</p><p>The <a href="../c3ref/c_abort.html">SQLITE_BUSY</a> error is converted to <a href="../c3ref/c_ioerr_access.html">SQLITE_IOERR_BLOCKED</a>when SQLite is in the middle of a large transaction where all thechanges will not fit into the in-memory cache.  SQLite willalready hold a RESERVED lock on the database file, but it needsto promote this lock to EXCLUSIVE so that it can spill cachepages into the database file without harm to concurrentreaders.  If it is unable to promote the lock, then the in-memorycache will be left in an inconsistent state and so the errorcode is promoted from the relatively benign <a href="../c3ref/c_abort.html">SQLITE_BUSY</a> tothe more severe <a href="../c3ref/c_ioerr_access.html">SQLITE_IOERR_BLOCKED</a>.  This error code promotionforces an automatic rollback of the changes.  See the<a href="/cvstrac/wiki?p=CorruptionFollowingBusyError">CorruptionFollowingBusyError</a> wiki page for a discussion of whythis is important.</p><p>There can only be a single busy handler defined for each<a href="../c3ref/sqlite3.html">database connection</a>.  Setting a new busy handler clears anypreviously set handler.  Note that calling <a href="../c3ref/busy_timeout.html">sqlite3_busy_timeout()</a>will also set or clear the busy handler.</p><p>The busy callback should not take any actions which modify thedatabase connection that invoked the busy handler.  Any such actionsresult in undefined behavior.</p><p><h3>Invariants:</h3><table border="0" cellpadding="5" cellspacing="0"><tr><td valign="top">H12311</td> <td valign="top">The <a href="../c3ref/busy_handler.html">sqlite3_busy_handler(D,C,A)</a> function shall replacebusy callback in the <a href="../c3ref/sqlite3.html">database connection</a> D with a newa new busy handler C and application data pointer A.</td></tr><tr><td valign="top">H12312</td> <td valign="top">Newly created <a href="../c3ref/sqlite3.html">database connections</a> shall have a busyhandler of NULL.</td></tr><tr><td valign="top">H12314</td> <td valign="top">When two or more <a href="../c3ref/sqlite3.html">database connections</a> share a<a href="../c3ref/enable_shared_cache.html">common cache</a>,the busy handler for the database connection currently usingthe cache shall be invoked when the cache encounters a lock.</td></tr><tr><td valign="top">H12316</td> <td valign="top">If a busy handler callback returns zero, then the SQLite interfacethat provoked the locking event shall return <a href="../c3ref/c_abort.html">SQLITE_BUSY</a>.</td></tr><tr><td valign="top">H12318</td> <td valign="top">SQLite shall invokes the busy handler with two arguments whichare a copy of the pointer supplied by the 3rd parameter to<a href="../c3ref/busy_handler.html">sqlite3_busy_handler()</a> and a count of the number of priorinvocations of the busy handler for the same locking event.</td></tr></table></p><p><h3>Assumptions:</h3><table border="0" cellpadding="5" cellspacing="0"><tr><td valign="top">A12319</td> <td valign="top">A busy handler must not close the database connectionor <a href="../c3ref/stmt.html">prepared statement</a> that invoked the busy handler.</td></tr></table></p><p>See also lists of  <a href="objlist.html">Objects</a>,  <a href="constlist.html">Constants</a>, and  <a href="funclist.html">Functions</a>.</p><hr><small><i>This page last modified 2008/12/09 18:44:04 UTC</i></small></div></body></html>
⌨️ 快捷键说明

复制代码 Ctrl + C
搜索代码 Ctrl + F
全屏模式 F11
切换主题 Ctrl + Shift + D
显示快捷键 ?
增大字号 Ctrl + =
减小字号 Ctrl + -