📄 busy_handler.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 identifies a callback function that might beinvoked whenever an attempt is made to open a database tablethat another thread or process has locked.If the busy callback is NULL, then <a href="../c3ref/c_abort.html">SQLITE_BUSY</a>or <a href="../c3ref/c_ioerr_blocked.html">SQLITE_IOERR_BLOCKED</a>is returned immediately upon encountering the lock.If the busy callback is not NULL, then thecallback will be invoked with two arguments. Thefirst argument to the handler is a copy of the void* pointer whichis the third argument to this routine. The second argument tothe handler 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_blocked.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 thatit will be invoked when there is lock contention.If SQLite determines that invoking the busy handler could result ina deadlock, it will go ahead and return <a href="../c3ref/c_abort.html">SQLITE_BUSY</a> or<a href="../c3ref/c_ioerr_blocked.html">SQLITE_IOERR_BLOCKED</a> instead of invoking thebusy 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_blocked.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_blocked.html">SQLITE_IOERR_BLOCKED</a>. This error code promotionforces an automatic rollback of the changes. See the<a href="http://www.sqlite.org/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 databaseconnection. Setting a new busy handler clears any previous one.Note that calling <a href="../c3ref/busy_timeout.html">sqlite3_busy_timeout()</a> will also set or clearthe busy handler.</p><p><h3>Invariants:</h3><table border="0" cellpadding="5" cellspacing="0"><tr><td valign="top">F12311</td> <td valign="top">The <a href="../c3ref/busy_handler.html">sqlite3_busy_handler()</a> function replaces the busy handlercallback in the database connection identified by the 1stparameter with a new busy handler identified by the 2nd and 3rdparameters.</td></tr><tr><td valign="top">F12312</td> <td valign="top">The default busy handler for new database connections is NULL.</td></tr><tr><td valign="top">F12314</td> <td valign="top">When two or more database connection share a common cache,the busy handler for the database connection currently usingthe cache is invoked when the cache encounters a lock.</td></tr><tr><td valign="top">F12316</td> <td valign="top">If a busy handler callback returns zero, then the SQLiteinterface that provoked the locking event will return<a href="../c3ref/c_abort.html">SQLITE_BUSY</a>.</td></tr><tr><td valign="top">F12318</td> <td valign="top">SQLite will invokes the busy handler with two argument 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>Limitations:</h3><table border="0" cellpadding="5" cellspacing="0"><tr><td valign="top">U12319</td> <td valign="top">A busy handler should not call close the database connectionor prepared statement 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/05/12 13:08:44 UTC</i></small></div></body></html>⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -