Debian Codegraph @

www/c3ref/busy_handler.html

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