Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Update unlock_notify.html to include a wrapper for sqlite3_prepare_v2(). |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA1: |
c020c0034cd2bfc1054ac46aa3dd0aeb |
User & Date: | dan 2009-03-19 09:01:19.000 |
Context
2009-03-22
| ||
20:48 | Mark the INDEXED token as being usable as an object name. (check-in: d2a68d4718 user: drh tags: trunk) | |
2009-03-19
| ||
09:01 | Update unlock_notify.html to include a wrapper for sqlite3_prepare_v2(). (check-in: c020c0034c user: dan tags: trunk) | |
00:04 | Fix a typo in the limits.html document. (check-in: 6ddbe9cdf0 user: drh tags: trunk) | |
Changes
Changes to pages/unlock_notify.in.
︙ | ︙ | |||
19 20 21 22 23 24 25 | proc C_Code {text} { hd_puts "<pre>\n" set iLine 0 foreach zLine [split [string trim $text "\n"] "\n"] { set zLine [string map {< < > >} $zLine] set zSubspec {<span style="color:blue;font-style:italic">&</span>} regsub {(/\*|^ *\*\*|\*/).*} $zLine $zSubspec zLine | | > > | 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 | proc C_Code {text} { hd_puts "<pre>\n" set iLine 0 foreach zLine [split [string trim $text "\n"] "\n"] { set zLine [string map {< < > >} $zLine] set zSubspec {<span style="color:blue;font-style:italic">&</span>} regsub {(/\*|^ *\*\*|\*/).*} $zLine $zSubspec zLine if {[regexp {(.*)(sqlite3[a-z0-9_]*)(.*)} $zLine -> one two three] && $two ne "sqlite3_blocking_prepare_v2" } { hd_puts $one hd_resolve "\[$two\]" hd_puts $three } else { hd_puts $zLine } hd_puts "\n" |
︙ | ︙ | |||
57 58 59 60 61 62 63 64 65 | 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 [sqlite3_step()] returns SQLITE_LOCKED. <p> This page presents a technique using the SQLite [sqlite3_unlock_notify()] | > > > > > > > | | | > | | | | | | | | | | | | | | | 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 | 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 [sqlite3_step()] returns SQLITE_LOCKED. <p> Although it is less common, a call to [sqlite3_prepare()] or [sqlite3_prepare_v2()] may also return SQLITE_LOCKED if it cannot obtain a read-lock on the sqlite_master table of each attached database. These APIs need to read the schema data contained in the sqlite_master table in order to compile SQL statements to [sqlite3_stmt*] objects. <p> This page presents a technique using the SQLite [sqlite3_unlock_notify()] API to create a versions of [sqlite3_step()] and [sqlite3_prepare_v2()] that block until the required locks are available instead of returning SQLITE_LOCKED immediately, for use in multi-threaded applications. 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 [sqlite3_unlock_notify()] API, which is only available if the library is compiled with the pre-processor symbol [SQLITE_ENABLE_UNLOCK_NOTIFY] defined, is [sqlite3_unlock_notify | documented here]. This page is no substitute for reading the full API documentation! <p><b>The sqlite3_unlock_notify() API</b> <p> After a call to [sqlite3_step()] or [sqlite3_prepare_v2()] returns SQLITE_LOCKED, the [sqlite3_unlock_notify()] 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 [sqlite3_step()] or [sqlite3_prepare_v2()] 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 [sqlite3_unlock_notify()] 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 at random and issues the unlock-notify callback when that connection's transaction is finished. |
︙ | ︙ | |||
113 114 115 116 117 118 119 | 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. | | > > > | > > > | | 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 | 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 [sqlite3_unlock_notify()] 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. <p> The algorithm used by the sqlite3_blocking_prepare_v2() function is similar, except that step 4 (reseting the statement handle) is omitted. </ol> <p><b>Writer Starvation</b> <p> Based on the description above, it could be concluded that if there are sufficient database readers reading the same table often enough, it is |
︙ | ︙ | |||
153 154 155 156 157 158 159 | <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 | | | | | | | | > | | | | | | | | | | | | 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 | <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 [sqlite3_unlock_notify()] 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 as, 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 [sqlite3_unlock_notify()] 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 [sqlite3_unlock_notify()] returns. Or, it is possible that the unlock-notify callback is invoked by a second thread after [sqlite3_unlock_notify()] is called but before the thread starts waiting to be asynchronously signalled. <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 [sqlite3_unlock_notify()] 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> Atomicly 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 on this page 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 [sqlite3_unlock_notify()] 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 marshalled into an array and a single callback issued. If each thread were assigned a priority, then instead of just signalling the threads in arbitrary order as this implementation does, higher priority threads could be signalled before lower priority threads. <p> If a "DROP TABLE" or "DROP INDEX" SQL command is executed, and the associated database connection currently has one or more actively executing SELECT statements, then SQLITE_LOCKED is returned. If [sqlite3_unlock_notify()] is called in this case, then the specified callback will be invoked immediately. Unless the other running SELECT statements complete execution in the meantime, 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 extended error codes. When it is appropriate to call [sqlite3_unlock_notify()], 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> |