summaryrefslogtreecommitdiffstats
path: root/www/unlock_notify.html
blob: 1e777b37bd85d164dfbc31e7e65c87efde5bced0 (plain)
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
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
<!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>SQLite Unlock-Notify API</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>



<style>
  pre a:visited, pre a:link { text-decoration: none ; color: #40534b }
  pre {
    background: #F3F3F3;
    float: right;
    padding: 1ex 2ex;
    margin-left: 1em;
    border: solid black 1px;
  }
  h1,h2 { clear: both ; text-align: center }
</style>

<h1>Using the sqlite3_unlock_notify() API</h1>

<pre>
<span style="color:blue;font-style:italic">/* This example uses the pthreads API */</span>
#include &lt;pthread.h&gt;

<span style="color:blue;font-style:italic">/*</span>
<span style="color:blue;font-style:italic">** A pointer to an instance of this structure is passed as the user-context</span>
<span style="color:blue;font-style:italic">** pointer when registering for an unlock-notify callback.</span>
<span style="color:blue;font-style:italic">*/</span>
typedef struct UnlockNotification UnlockNotification;
struct UnlockNotification {
  int fired;                         <span style="color:blue;font-style:italic">/* True after unlock event has occurred */</span>
  pthread_cond_t cond;               <span style="color:blue;font-style:italic">/* Condition variable to wait on */</span>
  pthread_mutex_t mutex;             <span style="color:blue;font-style:italic">/* Mutex to protect structure */</span>
};

<span style="color:blue;font-style:italic">/*</span>
<span style="color:blue;font-style:italic">** This function is an unlock-notify callback registered with SQLite.</span>
<span style="color:blue;font-style:italic">*/</span>
static void unlock_notify_cb(void **apArg, int nArg){
  int i;
  for(i=0; i&lt;nArg; i++){
    UnlockNotification *p = (UnlockNotification *)apArg[i];
    pthread_mutex_lock(&p-&gt;mutex);
    p-&gt;fired = 1;
    pthread_cond_signal(&p-&gt;cond);
    pthread_mutex_unlock(&p-&gt;mutex);
  }
}

<span style="color:blue;font-style:italic">/*</span>
<span style="color:blue;font-style:italic">** This function assumes that an SQLite API call (either <a href="c3ref/prepare.html">sqlite3_prepare_v2</a>() </span>
<span style="color:blue;font-style:italic">** or <a href="c3ref/step.html">sqlite3_step</a>()) has just returned SQLITE_LOCKED. The argument is the</span>
<span style="color:blue;font-style:italic">** associated database connection.</span>
<span style="color:blue;font-style:italic">**</span>
<span style="color:blue;font-style:italic">** This function calls <a href="c3ref/unlock_notify.html">sqlite3_unlock_notify</a>() to register for an </span>
<span style="color:blue;font-style:italic">** unlock-notify callback, then blocks until that callback is delivered </span>
<span style="color:blue;font-style:italic">** and returns SQLITE_OK. The caller should then retry the failed operation.</span>
<span style="color:blue;font-style:italic">**</span>
<span style="color:blue;font-style:italic">** Or, if <a href="c3ref/unlock_notify.html">sqlite3_unlock_notify</a>() indicates that to block would deadlock </span>
<span style="color:blue;font-style:italic">** the system, then this function returns SQLITE_LOCKED immediately. In </span>
<span style="color:blue;font-style:italic">** this case the caller should not retry the operation and should roll </span>
<span style="color:blue;font-style:italic">** back the current transaction (if any).</span>
<span style="color:blue;font-style:italic">*/</span>
static int wait_for_unlock_notify(<a href="c3ref/sqlite3.html">sqlite3</a> *db){
  int rc;
  UnlockNotification un;

  <span style="color:blue;font-style:italic">/* Initialize the UnlockNotification structure. */</span>
  un.fired = 0;
  pthread_mutex_init(&un.mutex, 0);
  pthread_cond_init(&un.cond, 0);

  <span style="color:blue;font-style:italic">/* Register for an unlock-notify callback. */</span>
  rc = <a href="c3ref/unlock_notify.html">sqlite3_unlock_notify</a>(db, unlock_notify_cb, (void *)&un);
  assert( rc==SQLITE_LOCKED || rc==SQLITE_OK );

  <span style="color:blue;font-style:italic">/* The call to <a href="c3ref/unlock_notify.html">sqlite3_unlock_notify</a>() always returns either SQLITE_LOCKED </span>
<span style="color:blue;font-style:italic">  ** or SQLITE_OK. </span>
<span style="color:blue;font-style:italic">  **</span>
<span style="color:blue;font-style:italic">  ** If SQLITE_LOCKED was returned, then the system is deadlocked. In this</span>
<span style="color:blue;font-style:italic">  ** case this function needs to return SQLITE_LOCKED to the caller so </span>
<span style="color:blue;font-style:italic">  ** that the current transaction can be rolled back. Otherwise, block</span>
<span style="color:blue;font-style:italic">  ** until the unlock-notify callback is invoked, then return SQLITE_OK.</span>
  <span style="color:blue;font-style:italic">*/</span>
  if( rc==SQLITE_OK ){
    pthread_mutex_lock(&un.mutex);
    if( !un.fired ){
      pthread_cond_wait(&un.cond, &un.mutex);
    }
    pthread_mutex_unlock(&un.mutex);
  }

  <span style="color:blue;font-style:italic">/* Destroy the mutex and condition variables. */</span>
  pthread_cond_destroy(&un.cond);
  pthread_mutex_destroy(&un.mutex);

  return rc;
}

<span style="color:blue;font-style:italic">/*</span>
<span style="color:blue;font-style:italic">** This function is a wrapper around the SQLite function <a href="c3ref/step.html">sqlite3_step</a>().</span>
<span style="color:blue;font-style:italic">** It functions in the same way as step(), except that if a required</span>
<span style="color:blue;font-style:italic">** shared-cache lock cannot be obtained, this function may block waiting for</span>
<span style="color:blue;font-style:italic">** the lock to become available. In this scenario the normal API step()</span>
<span style="color:blue;font-style:italic">** function always returns SQLITE_LOCKED.</span>
<span style="color:blue;font-style:italic">**</span>
<span style="color:blue;font-style:italic">** If this function returns SQLITE_LOCKED, the caller should rollback</span>
<span style="color:blue;font-style:italic">** the current transaction (if any) and try again later. Otherwise, the</span>
<span style="color:blue;font-style:italic">** system may become deadlocked.</span>
<span style="color:blue;font-style:italic">*/</span>
int sqlite3_blocking_step(<a href="c3ref/stmt.html">sqlite3_stmt</a> *pStmt){
  int rc;
  while( SQLITE_LOCKED==(rc = <a href="c3ref/step.html">sqlite3_step</a>(pStmt)) ){
    rc = wait_for_unlock_notify(<a href="c3ref/db_handle.html">sqlite3_db_handle</a>(pStmt));
    if( rc!=SQLITE_OK ) break;
    <a href="c3ref/reset.html">sqlite3_reset</a>(pStmt);
  }
  return rc;
}

<span style="color:blue;font-style:italic">/*</span>
<span style="color:blue;font-style:italic">** This function is a wrapper around the SQLite function <a href="c3ref/prepare.html">sqlite3_prepare_v2</a>().</span>
<span style="color:blue;font-style:italic">** It functions in the same way as prepare_v2(), except that if a required</span>
<span style="color:blue;font-style:italic">** shared-cache lock cannot be obtained, this function may block waiting for</span>
<span style="color:blue;font-style:italic">** the lock to become available. In this scenario the normal API prepare_v2()</span>
<span style="color:blue;font-style:italic">** function always returns SQLITE_LOCKED.</span>
<span style="color:blue;font-style:italic">**</span>
<span style="color:blue;font-style:italic">** If this function returns SQLITE_LOCKED, the caller should rollback</span>
<span style="color:blue;font-style:italic">** the current transaction (if any) and try again later. Otherwise, the</span>
<span style="color:blue;font-style:italic">** system may become deadlocked.</span>
<span style="color:blue;font-style:italic">*/</span>
int sqlite3_blocking_prepare_v2(
  <a href="c3ref/sqlite3.html">sqlite3</a> *db,              <span style="color:blue;font-style:italic">/* Database handle. */</span>
  const char *zSql,         <span style="color:blue;font-style:italic">/* UTF-8 encoded SQL statement. */</span>
  int nSql,                 <span style="color:blue;font-style:italic">/* Length of zSql in bytes. */</span>
  <a href="c3ref/stmt.html">sqlite3_stmt</a> **ppStmt,    <span style="color:blue;font-style:italic">/* OUT: A pointer to the prepared statement */</span>
  const char **pz           <span style="color:blue;font-style:italic">/* OUT: End of parsed string */</span>
){
  int rc;
  while( SQLITE_LOCKED==(rc = <a href="c3ref/prepare.html">sqlite3_prepare_v2</a>(db, zSql, nSql, ppStmt, pz)) ){
    rc = wait_for_unlock_notify(db);
    if( rc!=SQLITE_OK ) break;
  }
  return rc;
}
</pre>


<p>
  When two or more connections access the same database in shared-cache 
  mode, read and write (shared and exclusive) locks on individual tables
  are used to ensure that concurrently executing transactions are kept 
  isolated. Before writing to a table, a write (exclusive) lock must be 
  obtained on that table. Before reading, a read (shared) lock must be
  obtained. A connection releases all held table locks when it concludes
  its transaction. If a connection cannot obtain a required lock, then
  the call to <a href="c3ref/step.html">sqlite3_step()</a> returns SQLITE_LOCKED.

<p>
  Although it is less common, a call to <a href="c3ref/prepare.html">sqlite3_prepare()</a> or
  <a href="c3ref/prepare.html">sqlite3_prepare_v2()</a> may also return SQLITE_LOCKED if it cannot obtain
  a read-lock on the <a href="schematab.html">sqlite_schema table</a> of each attached database. These
  APIs need to read the schema data contained in the sqlite_schema table
  in order to compile SQL statements to <a href="c3ref/stmt.html">sqlite3_stmt*</a> objects.

<p>
  This article presents a technique using the SQLite <a href="c3ref/unlock_notify.html">sqlite3_unlock_notify()</a>
  interface such that calls to <a href="c3ref/step.html">sqlite3_step()</a> and <a href="c3ref/prepare.html">sqlite3_prepare_v2()</a>
  block until the required locks are available instead of returning 
  SQLITE_LOCKED immediately. If the
  sqlite3_blocking_step() or sqlite3_blocking_prepare_v2() functions presented 
  to the left return SQLITE_LOCKED, this indicates that to block would 
  deadlock the system.

<p>
  The <a href="c3ref/unlock_notify.html">sqlite3_unlock_notify()</a> API, which is only available if the library is
  compiled with the pre-processor symbol <a href="compile.html#enable_unlock_notify">SQLITE_ENABLE_UNLOCK_NOTIFY</a> defined,
  is <a href="c3ref/unlock_notify.html">documented here</a>. This article is not a
  substitute for reading the full API documentation!

<p>
  The <a href="c3ref/unlock_notify.html">sqlite3_unlock_notify()</a> interface is designed for use in systems
  that have a separate thread assigned to each <a href="c3ref/sqlite3.html">database connection</a>.  There
  is nothing in the implementation that prevents a single thread from running
  multiple database connections.  However, the <a href="c3ref/unlock_notify.html">sqlite3_unlock_notify()</a>
  interface only works on a single connection at a time, so the lock
  resolution logic presented here will only work for a single 
  database connection per thread.

<p><b>The sqlite3_unlock_notify() API</b>

<p>
  After a call to <a href="c3ref/step.html">sqlite3_step()</a> or <a href="c3ref/prepare.html">sqlite3_prepare_v2()</a> returns 
  SQLITE_LOCKED, the <a href="c3ref/unlock_notify.html">sqlite3_unlock_notify()</a> API may be invoked to register 
  for an unlock-notify callback. The unlock-notify callback is invoked by 
  SQLite after the database connection holding the table-lock that prevented
  the call to <a href="c3ref/step.html">sqlite3_step()</a> or <a href="c3ref/prepare.html">sqlite3_prepare_v2()</a> from succeeding has
  finished its transaction and released all locks. For example, if a call to
  sqlite3_step() is an attempt to read from table X, and some other connection
  Y is holding a write-lock on table X, then sqlite3_step() will return
  SQLITE_LOCKED. If <a href="c3ref/unlock_notify.html">sqlite3_unlock_notify()</a> is then called, the unlock-notify
  callback will be invoked after connection Y's transaction is concluded. The
  connection that the unlock-notify callback is waiting on, in this case
  connection Y, is known as the "blocking connection".

<p>
  If a call to sqlite3_step() that attempts to write to a database table
  returns SQLITE_LOCKED, then more than one other connection may be holding 
  a read-lock on the database table in question. In this case SQLite simply
  selects one of those other connections arbitrarily and issues the 
  unlock-notify callback when that connection's transaction is finished.
  Whether the call to sqlite3_step() was blocked by one or many connections, 
  when the corresponding unlock-notify callback is issued it is not 
  guaranteed that the required lock is available, only that it may be.

<p>
  When the unlock-notify callback is issued, it is issued from within a
  call to sqlite3_step() (or sqlite3_close()) associated with the blocking 
  connection. It is illegal to invoke any sqlite3_XXX() API functions from
  within an unlock-notify callback. The expected use is that the unlock-notify
  callback will signal some other waiting thread or schedule some action
  to take place later.

<p>
  The algorithm used by the sqlite3_blocking_step() function is as follows:

<ol>
  <li><p> Call sqlite3_step() on the supplied statement handle. If the call
       returns anything other than SQLITE_LOCKED, then return this value
       to the caller. Otherwise, continue.

  <li><p> Invoke <a href="c3ref/unlock_notify.html">sqlite3_unlock_notify()</a> on the database connection handle
       associated with the supplied statement handle to register for an
       unlock-notify callback. If the call to unlock_notify() returns
       SQLITE_LOCKED, then return this value to the caller.

  <li><p> Block until the unlock-notify callback is invoked by another thread.

  <li><p> Call sqlite3_reset() on the statement handle. Since an 
       SQLITE_LOCKED error may only occur on the first call to sqlite3_step()
       (it is not possible for one call to sqlite3_step() to return 
       SQLITE_ROW and then the next SQLITE_LOCKED), the statement handle may 
       be reset at this point without affecting the results of the query
       from the point of view of the caller. If sqlite3_reset() were not
       called at this point, the next call to sqlite3_step() would return
       SQLITE_MISUSE.

  <li><p> Return to step 1.
</ol>

<p>
  The algorithm used by the sqlite3_blocking_prepare_v2() function is similar,
  except that step 4 (resetting the statement handle) is omitted.


<p><b>Writer Starvation</b>

<p>
  Multiple connections may hold a read-lock simultaneously.  If many threads
  are acquiring overlapping read-locks, it might be the case that at least
  one thread is always holding a read lock.
  Then a table waiting for a write-lock will wait forever.
  This scenario is called "writer starvation."

<p>
  SQLite helps applications avoid writer starvation. After any attempt to
  obtain a write-lock on a table fails (because one or more other 
  connections are holding read-locks), all attempts to open new transactions
  on the shared-cache fail until one of the following is true:

<ul>
  <li> The current writer concludes its transaction, OR
  <li> The number of open read-transactions on the shared-cache drops to zero.
</ul>

<p>
  Failed attempts to open new read-transactions return SQLITE_LOCKED to the
  caller. If the caller then calls <a href="c3ref/unlock_notify.html">sqlite3_unlock_notify()</a> to register for
  an unlock-notify callback, the blocking connection is the connection that
  currently has an open write-transaction on the shared-cache. This prevents
  writer-starvation since if no new read-transactions may be opened and 
  assuming all existing read-transactions are eventually concluded, the 
  writer will eventually have an opportunity to obtain the required
  write-lock.

<p><b>The pthreads API</b>

  <p> By the time <a href="c3ref/unlock_notify.html">sqlite3_unlock_notify()</a> is invoked by
      wait_for_unlock_notify(), it is possible that the blocking connection
      that prevented the sqlite3_step() or sqlite3_prepare_v2() call from 
      succeeding has already finished its transaction. In this case, the 
      unlock-notify callback is invoked immediately, before 
      <a href="c3ref/unlock_notify.html">sqlite3_unlock_notify()</a> returns. Or, it is possible that the 
      unlock-notify callback is invoked by a second thread after 
      <a href="c3ref/unlock_notify.html">sqlite3_unlock_notify()</a> is called but before the thread starts waiting 
      to be asynchronously signaled. 

  <p> Exactly how such a potential race-condition is handled depends on the
      threads and synchronization primitives interface used by the application.
      This example uses pthreads, the interface provided by modern UNIX-like 
      systems, including Linux.

  <p> The pthreads interface provides the pthread_cond_wait() function. 
      This function allows the caller to simultaneously release a mutex
      and start waiting for an asynchronous signal. Using this function,
      a "fired" flag and a mutex, the race-condition described above may
      be eliminated as follows:

  <p> When the unlock-notify callback is invoked, which may be before the
      thread that called <a href="c3ref/unlock_notify.html">sqlite3_unlock_notify()</a> begins waiting for the 
      asynchronous signal, it does the following:

    <ol>
      <li> Obtains the mutex.
      <li> Sets the "fired" flag to true.
      <li> Attempts to signal a waiting thread.
      <li> Releases the mutex.
    </ol>

  <p> When the wait_for_unlock_notify() thread is ready to begin waiting for
      the unlock-notify callback to arrive, it:

    <ol>
      <li> Obtains the mutex.
      <li> Checks if the "fired" flag has been set. If so, the unlock-notify
           callback has already been invoked. Release the mutex and continue.
      <li> Atomically releases the mutex and begins waiting for the
           asynchronous signal. When the signal arrives, continue.
    </ol>

  <p> This way, it doesn't matter if the unlock-notify callback has already
      been invoked, or is being invoked, when the wait_for_unlock_notify() 
      thread begins blocking.

<p><b>Possible Enhancements</b>

  <p> The code in this article could be improved in at least two ways:

  <ul>
    <li> It could manage thread priorities.
    <li> It could handle a special case of SQLITE_LOCKED that can occur
         when dropping a table or index.
  </ul>

  <p>
    Even though the <a href="c3ref/unlock_notify.html">sqlite3_unlock_notify()</a> function only allows the caller
    to specify a single user-context pointer, an unlock-notify callback 
    is passed an array of such context pointers. This is because if when
    a blocking connection concludes its transaction, if there is more
    than one unlock-notify registered to call the same C function, the
    context-pointers are marshaled into an array and a single callback
    issued. If each thread were assigned a priority, then instead of just
    signaling the threads in arbitrary order as this implementation does,
    higher priority threads could be signaled before lower priority threads.

  <p>
    If a "DROP TABLE" or "DROP INDEX" SQL command is executed, and the
    same database connection currently has one or more actively
    executing SELECT statements, then SQLITE_LOCKED is returned. If
    <a href="c3ref/unlock_notify.html">sqlite3_unlock_notify()</a> is called in this case, then the specified
    callback will be invoked immediately. Re-attempting the "DROP
    TABLE" or "DROP INDEX" statement will return another SQLITE_LOCKED 
    error. In the implementation of sqlite3_blocking_step() shown to the
    left, this could cause an infinite loop.

  <p>
    The caller could distinguish between this special "DROP TABLE|INDEX" 
    case and other cases by using <a href="rescode.html#extrc">extended error codes</a>. When it is appropriate
    to call <a href="c3ref/unlock_notify.html">sqlite3_unlock_notify()</a>, the extended error code is
    SQLITE_LOCKED_SHAREDCACHE. Otherwise, in the "DROP TABLE|INDEX" case,
    it is just plain SQLITE_LOCKED. Another solution might be to limit
    the number of times that any single query could be reattempted (to say 
    100). Although this might be less efficient than one might wish, the 
    situation in question is not likely to occur often.

<div style="clear:both"></div>
<p align="center"><small><i>This page last modified on  <a href="https://sqlite.org/docsrc/honeypot" id="mtimelink"  data-href="https://sqlite.org/docsrc/finfo/pages/unlock_notify.in?m=490fe96500">2022-01-08 05:02:57</a> UTC </small></i></p>