1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
<!DOCTYPE html>
<html><head>
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<link href="../sqlite.css" rel="stylesheet">
<title>Register A Callback To Handle SQLITE_BUSY Errors</title>
<!-- path=../ -->
</head>
<body>
<div class=nosearch>
<a href="../index.html">
<img class="logo" src="../images/sqlite370_banner.gif" alt="SQLite" border="0">
</a>
<div><!-- IE hack to prevent disappearing logo --></div>
<div class="tagline desktoponly">
Small. Fast. Reliable.<br>Choose any three.
</div>
<div class="menu mainmenu">
<ul>
<li><a href="../index.html">Home</a>
<li class='mobileonly'><a href="javascript:void(0)" onclick='toggle_div("submenu")'>Menu</a>
<li class='wideonly'><a href='../about.html'>About</a>
<li class='desktoponly'><a href="../docs.html">Documentation</a>
<li class='desktoponly'><a href="../download.html">Download</a>
<li class='wideonly'><a href='../copyright.html'>License</a>
<li class='desktoponly'><a href="../support.html">Support</a>
<li class='desktoponly'><a href="../prosupport.html">Purchase</a>
<li class='search' id='search_menubutton'>
<a href="javascript:void(0)" onclick='toggle_search()'>Search</a>
</ul>
</div>
<div class="menu submenu" id="submenu">
<ul>
<li><a href='../about.html'>About</a>
<li><a href='../docs.html'>Documentation</a>
<li><a href='../download.html'>Download</a>
<li><a href='../support.html'>Support</a>
<li><a href='../prosupport.html'>Purchase</a>
</ul>
</div>
<div class="searchmenu" id="searchmenu">
<form method="GET" action="../search">
<select name="s" id="searchtype">
<option value="d">Search Documentation</option>
<option value="c">Search Changelog</option>
</select>
<input type="text" name="q" id="searchbox" value="">
<input type="submit" value="Go">
</form>
</div>
</div>
<script>
function toggle_div(nm) {
var w = document.getElementById(nm);
if( w.style.display=="block" ){
w.style.display = "none";
}else{
w.style.display = "block";
}
}
function toggle_search() {
var w = document.getElementById("searchmenu");
if( w.style.display=="block" ){
w.style.display = "none";
} else {
w.style.display = "block";
setTimeout(function(){
document.getElementById("searchbox").focus()
}, 30);
}
}
function div_off(nm){document.getElementById(nm).style.display="none";}
window.onbeforeunload = function(e){div_off("submenu");}
/* Disable the Search feature if we are not operating from CGI, since */
/* Search is accomplished using CGI and will not work without it. */
if( !location.origin || !location.origin.match || !location.origin.match(/http/) ){
document.getElementById("search_menubutton").style.display = "none";
}
/* Used by the Hide/Show button beside syntax diagrams, to toggle the */
function hideorshow(btn,obj){
var x = document.getElementById(obj);
var b = document.getElementById(btn);
if( x.style.display!='none' ){
x.style.display = 'none';
b.innerHTML='show';
}else{
x.style.display = '';
b.innerHTML='hide';
}
return false;
}
var antiRobot = 0;
function antiRobotGo(){
if( antiRobot!=3 ) return;
antiRobot = 7;
var j = document.getElementById("mtimelink");
if(j && j.hasAttribute("data-href")) j.href=j.getAttribute("data-href");
}
function antiRobotDefense(){
document.body.onmousedown=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousedown=null;
}
document.body.onmousemove=function(){
antiRobot |= 2;
antiRobotGo();
document.body.onmousemove=null;
}
setTimeout(function(){
antiRobot |= 1;
antiRobotGo();
}, 100)
antiRobotGo();
}
antiRobotDefense();
</script>
<!-- keywords: {busy handler} {busy-handler callback} sqlite3_busy_handler -->
<div class=nosearch>
<a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
<h2>Register A Callback To Handle SQLITE_BUSY Errors</h2>
</div>
<blockquote><pre>
int sqlite3_busy_handler(sqlite3*,int(*)(void*,int),void*);
</pre></blockquote>
<p>
The sqlite3_busy_handler(D,X,P) routine sets a callback function X
that might be invoked with argument P whenever
an attempt is made to access a database table associated with
<a href="../c3ref/sqlite3.html">database connection</a> D when another thread
or process has the table locked.
The sqlite3_busy_handler() interface is used to implement
<a href="../c3ref/busy_timeout.html">sqlite3_busy_timeout()</a> and <a href="../pragma.html#pragma_busy_timeout">PRAGMA busy_timeout</a>.</p>
<p>If the busy callback is NULL, then <a href="../rescode.html#busy">SQLITE_BUSY</a>
is returned immediately upon encountering the lock. If the busy callback
is not NULL, then the callback might be invoked with two arguments.</p>
<p>The first argument to the busy handler is a copy of the void* pointer which
is the third argument to sqlite3_busy_handler(). The second argument to
the busy handler callback is the number of times that the busy handler has
been invoked previously for the same locking event. If the
busy callback returns 0, then no additional attempts are made to
access the database and <a href="../rescode.html#busy">SQLITE_BUSY</a> is returned
to the application.
If the callback returns non-zero, then another attempt
is made to access the database and the cycle repeats.</p>
<p>The presence of a busy handler does not guarantee that it will be invoked
when there is lock contention. If SQLite determines that invoking the busy
handler could result in a deadlock, it will go ahead and return <a href="../rescode.html#busy">SQLITE_BUSY</a>
to the application instead of invoking the
busy handler.
Consider a scenario where one process is holding a read lock that
it is trying to promote to a reserved lock and
a second process is holding a reserved lock that it is trying
to promote to an exclusive lock. The first process cannot proceed
because it is blocked by the second and the second process cannot
proceed because it is blocked by the first. If both processes
invoke the busy handlers, neither will make any progress. Therefore,
SQLite returns <a href="../rescode.html#busy">SQLITE_BUSY</a> for the first process, hoping that this
will induce the first process to release its read lock and allow
the second process to proceed.</p>
<p>The default busy callback is NULL.</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 any
previously set handler. Note that calling <a href="../c3ref/busy_timeout.html">sqlite3_busy_timeout()</a>
or evaluating <a href="../pragma.html#pragma_busy_timeout">PRAGMA busy_timeout=N</a> will change the
busy handler and thus clear any previously set busy handler.</p>
<p>The busy callback should not take any actions which modify the
database connection that invoked the busy handler. In other words,
the busy handler is not reentrant. Any such actions
result in undefined behavior.</p>
<p>A busy handler must not close the database connection
or <a href="../c3ref/stmt.html">prepared statement</a> that invoked the busy handler.
</p><p>See also lists of
<a href="../c3ref/objlist.html">Objects</a>,
<a href="../c3ref/constlist.html">Constants</a>, and
<a href="../c3ref/funclist.html">Functions</a>.</p>
|
