Debian Codegraph @

www/c3ref/unlock_notify.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>Unlock Notification</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: sqlite3_unlock_notify -->
119 <div class=nosearch>
120 <a href="../c3ref/intro.html"><h2>SQLite C Interface</h2></a>
121 <h2>Unlock Notification</h2>
122 </div>
123 <blockquote><pre>
124 int sqlite3_unlock_notify(
125 sqlite3 *pBlocked, /* Waiting connection */
126 void (*xNotify)(void **apArg, int nArg), /* Callback function to invoke */
127 void *pNotifyArg /* Argument to pass to xNotify */
128 );
129 </pre></blockquote>
130 <p>
131 When running in shared-cache mode, a database operation may fail with
132 an <a href="../rescode.html#locked">SQLITE_LOCKED</a> error if the required locks on the shared-cache or
133 individual tables within the shared-cache cannot be obtained. See
134 <a href="../sharedcache.html">SQLite Shared-Cache Mode</a> for a description of shared-cache locking.
135 This API may be used to register a callback that SQLite will invoke
136 when the connection currently holding the required lock relinquishes it.
137 This API is only available if the library was compiled with the
138 <a href="../compile.html#enable_unlock_notify">SQLITE_ENABLE_UNLOCK_NOTIFY</a> C-preprocessor symbol defined.</p>
139
140 <p>See Also: <a href="../unlock_notify.html">Using the SQLite Unlock Notification Feature</a>.</p>
141
142 <p>Shared-cache locks are released when a database connection concludes
143 its current transaction, either by committing it or rolling it back.</p>
144
145 <p>When a connection (known as the blocked connection) fails to obtain a
146 shared-cache lock and SQLITE_LOCKED is returned to the caller, the
147 identity of the database connection (the blocking connection) that
148 has locked the required resource is stored internally. After an
149 application receives an SQLITE_LOCKED error, it may call the
150 sqlite3_unlock_notify() method with the blocked connection handle as
151 the first argument to register for a callback that will be invoked
152 when the blocking connection's current transaction is concluded. The
153 callback is invoked from within the <a href="../c3ref/step.html">sqlite3_step</a> or <a href="../c3ref/close.html">sqlite3_close</a>
154 call that concludes the blocking connection's transaction.</p>
155
156 <p>If sqlite3_unlock_notify() is called in a multi-threaded application,
157 there is a chance that the blocking connection will have already
158 concluded its transaction by the time sqlite3_unlock_notify() is invoked.
159 If this happens, then the specified callback is invoked immediately,
160 from within the call to sqlite3_unlock_notify().</p>
161
162 <p>If the blocked connection is attempting to obtain a write-lock on a
163 shared-cache table, and more than one other connection currently holds
164 a read-lock on the same table, then SQLite arbitrarily selects one of
165 the other connections to use as the blocking connection.</p>
166
167 <p>There may be at most one unlock-notify callback registered by a
168 blocked connection. If sqlite3_unlock_notify() is called when the
169 blocked connection already has a registered unlock-notify callback,
170 then the new callback replaces the old. If sqlite3_unlock_notify() is
171 called with a NULL pointer as its second argument, then any existing
172 unlock-notify callback is canceled. The blocked connection's
173 unlock-notify callback may also be canceled by closing the blocked
174 connection using <a href="../c3ref/close.html">sqlite3_close()</a>.</p>
175
176 <p>The unlock-notify callback is not reentrant. If an application invokes
177 any sqlite3_xxx API functions from within an unlock-notify callback, a
178 crash or deadlock may be the result.</p>
179
180 <p>Unless deadlock is detected (see below), sqlite3_unlock_notify() always
181 returns SQLITE_OK.</p>
182
183 <p><b>Callback Invocation Details</b></p>
184
185 <p>When an unlock-notify callback is registered, the application provides a
186 single void* pointer that is passed to the callback when it is invoked.
187 However, the signature of the callback function allows SQLite to pass
188 it an array of void* context pointers. The first argument passed to
189 an unlock-notify callback is a pointer to an array of void* pointers,
190 and the second is the number of entries in the array.</p>
191
192 <p>When a blocking connection's transaction is concluded, there may be
193 more than one blocked connection that has registered for an unlock-notify
194 callback. If two or more such blocked connections have specified the
195 same callback function, then instead of invoking the callback function
196 multiple times, it is invoked once with the set of void* context pointers
197 specified by the blocked connections bundled together into an array.
198 This gives the application an opportunity to prioritize any actions
199 related to the set of unblocked database connections.</p>
200
201 <p><b>Deadlock Detection</b></p>
202
203 <p>Assuming that after registering for an unlock-notify callback a
204 database waits for the callback to be issued before taking any further
205 action (a reasonable assumption), then using this API may cause the
206 application to deadlock. For example, if connection X is waiting for
207 connection Y's transaction to be concluded, and similarly connection
208 Y is waiting on connection X's transaction, then neither connection
209 will proceed and the system may remain deadlocked indefinitely.</p>
210
211 <p>To avoid this scenario, the sqlite3_unlock_notify() performs deadlock
212 detection. If a given call to sqlite3_unlock_notify() would put the
213 system in a deadlocked state, then SQLITE_LOCKED is returned and no
214 unlock-notify callback is registered. The system is said to be in
215 a deadlocked state if connection A has registered for an unlock-notify
216 callback on the conclusion of connection B's transaction, and connection
217 B has itself registered for an unlock-notify callback when connection
218 A's transaction is concluded. Indirect deadlock is also detected, so
219 the system is also considered to be deadlocked if connection B has
220 registered for an unlock-notify callback on the conclusion of connection
221 C's transaction, where connection C is waiting on connection A. Any
222 number of levels of indirection are allowed.</p>
223
224 <p><b>The "DROP TABLE" Exception</b></p>
225
226 <p>When a call to <a href="../c3ref/step.html">sqlite3_step()</a> returns SQLITE_LOCKED, it is almost
227 always appropriate to call sqlite3_unlock_notify(). There is however,
228 one exception. When executing a "DROP TABLE" or "DROP INDEX" statement,
229 SQLite checks if there are any currently executing SELECT statements
230 that belong to the same connection. If there are, SQLITE_LOCKED is
231 returned. In this case there is no "blocking connection", so invoking
232 sqlite3_unlock_notify() results in the unlock-notify callback being
233 invoked immediately. If the application then re-attempts the "DROP TABLE"
234 or "DROP INDEX" query, an infinite loop might be the result.</p>
235
236 <p>One way around this problem is to check the extended error code returned
237 by an sqlite3_step() call. If there is a blocking connection, then the
238 extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in
239 the special "DROP TABLE/INDEX" case, the extended error code is just
240 SQLITE_LOCKED.
241 </p><p>See also lists of
242 <a href="../c3ref/objlist.html">Objects</a>,
243 <a href="../c3ref/constlist.html">Constants</a>, and
244 <a href="../c3ref/funclist.html">Functions</a>.</p>
245