*** DRAFT ***

SQLite Requirement Matrix Details
unlock_notify.html

Index Summary Markup Original


R-03816-21626-17112-32643-57381-58430-16315-21594 tcl slt th3 src

When running in shared-cache mode, a database operation may fail with an SQLITE_LOCKED error if the required locks on the shared-cache or individual tables within the shared-cache cannot be obtained.

/* IMP: R-03816-21626 */
# EVIDENCE-OF: R-03816-21626 When running in shared-cache mode, a
# database operation may fail with an SQLITE_LOCKED error if the
# required locks on the shared-cache or individual tables within the
# shared-cache cannot be obtained.

R-28453-47400-61335-60267-59373-07041-42359-06361 tcl slt th3 src

This API may be used to register a callback that SQLite will invoke when the connection currently holding the required lock relinquishes it.

/* IMP: R-28453-47400 */
# EVIDENCE-OF: R-28453-47400 This API may be used to register a callback
# that SQLite will invoke when the connection currently holding the
# required lock relinquishes it.

R-60349-29862-22141-07811-21559-44331-23137-45760 tcl slt th3 src

This API is only available if the library was compiled with the SQLITE_ENABLE_UNLOCK_NOTIFY C-preprocessor symbol defined.

/* IMP: R-60349-29862 */
# EVIDENCE-OF: R-60349-29862 This API is only available if the library
# was compiled with the SQLITE_ENABLE_UNLOCK_NOTIFY C-preprocessor
# symbol defined.

R-35088-43392-22185-31834-16686-27011-41097-22750 tcl slt th3 src

Shared-cache locks are released when a database connection concludes its current transaction, either by committing it or rolling it back.

/* IMP: R-35088-43392 */
# EVIDENCE-OF: R-35088-43392 Shared-cache locks are released when a
# database connection concludes its current transaction, either by
# committing it or rolling it back.

R-10886-33090-42835-40467-38387-59487-39282-25653 tcl slt th3 src

When a connection (known as the blocked connection) fails to obtain a shared-cache lock and SQLITE_LOCKED is returned to the caller, the identity of the database connection (the blocking connection) that has locked the required resource is stored internally.

/* IMP: R-10886-33090 */
# EVIDENCE-OF: R-10886-33090 When a connection (known as the blocked
# connection) fails to obtain a shared-cache lock and SQLITE_LOCKED is
# returned to the caller, the identity of the database connection (the
# blocking connection) that has locked the required resource is stored
# internally.

R-23120-24122-52717-58793-54182-36500-02638-57419 tcl slt th3 src

After an application receives an SQLITE_LOCKED error, it may call the sqlite3_unlock_notify() method with the blocked connection handle as the first argument to register for a callback that will be invoked when the blocking connections current transaction is concluded.

/* IMP: R-23120-24122 */
# EVIDENCE-OF: R-23120-24122 After an application receives an
# SQLITE_LOCKED error, it may call the sqlite3_unlock_notify() method
# with the blocked connection handle as the first argument to register
# for a callback that will be invoked when the blocking connections
# current transaction is concluded.

R-45920-48177-50080-31515-14083-57660-64476-49903 tcl slt th3 src

The callback is invoked from within the sqlite3_step or sqlite3_close call that concludes the blocking connections transaction.

/* IMP: R-45920-48177 */
# EVIDENCE-OF: R-45920-48177 The callback is invoked from within the
# sqlite3_step or sqlite3_close call that concludes the blocking
# connections transaction.

R-59847-53574-49799-21344-47903-30927-18789-48641 tcl slt th3 src

If sqlite3_unlock_notify() is called in a multi-threaded application, there is a chance that the blocking connection will have already concluded its transaction by the time sqlite3_unlock_notify() is invoked. If this happens, then the specified callback is invoked immediately, from within the call to sqlite3_unlock_notify().

/* IMP: R-59847-53574 */
# EVIDENCE-OF: R-59847-53574 If sqlite3_unlock_notify() is called in a
# multi-threaded application, there is a chance that the blocking
# connection will have already concluded its transaction by the time
# sqlite3_unlock_notify() is invoked. If this happens, then the
# specified callback is invoked immediately, from within the call to
# sqlite3_unlock_notify().

R-62860-04741-41366-30406-60752-17856-14374-30516 tcl slt th3 src

If the blocked connection is attempting to obtain a write-lock on a shared-cache table, and more than one other connection currently holds a read-lock on the same table, then SQLite arbitrarily selects one of the other connections to use as the blocking connection.

/* IMP: R-62860-04741 */
# EVIDENCE-OF: R-62860-04741 If the blocked connection is attempting to
# obtain a write-lock on a shared-cache table, and more than one other
# connection currently holds a read-lock on the same table, then SQLite
# arbitrarily selects one of the other connections to use as the
# blocking connection.

R-33626-44500-44579-55445-20026-07899-19169-03498 tcl slt th3 src

There may be at most one unlock-notify callback registered by a blocked connection. If sqlite3_unlock_notify() is called when the blocked connection already has a registered unlock-notify callback, then the new callback replaces the old.

/* IMP: R-33626-44500 */
# EVIDENCE-OF: R-33626-44500 There may be at most one unlock-notify
# callback registered by a blocked connection. If
# sqlite3_unlock_notify() is called when the blocked connection already
# has a registered unlock-notify callback, then the new callback
# replaces the old.

R-19139-12267-31476-22597-30278-48901-50934-33461 tcl slt th3 src

If sqlite3_unlock_notify() is called with a NULL pointer as its second argument, then any existing unlock-notify callback is canceled.

/* IMP: R-19139-12267 */
# EVIDENCE-OF: R-19139-12267 If sqlite3_unlock_notify() is called with a
# NULL pointer as its second argument, then any existing unlock-notify
# callback is canceled.

R-51594-01886-40324-04229-65116-14684-49683-32490 tcl slt th3 src

The blocked connections unlock-notify callback may also be canceled by closing the blocked connection using sqlite3_close().

/* IMP: R-51594-01886 */
# EVIDENCE-OF: R-51594-01886 The blocked connections unlock-notify
# callback may also be canceled by closing the blocked connection using
# sqlite3_close().

R-49752-52776-47662-23975-09882-64912-61393-46932 tcl slt th3 src

Unless deadlock is detected (see below), sqlite3_unlock_notify() always returns SQLITE_OK.

/* IMP: R-49752-52776 */
# EVIDENCE-OF: R-49752-52776 Unless deadlock is detected (see below),
# sqlite3_unlock_notify() always returns SQLITE_OK.

R-45092-55768-62322-65360-04224-03075-32666-24560 tcl slt th3 src

If two or more such blocked connections have specified the same callback function, then instead of invoking the callback function multiple times, it is invoked once with the set of void* context pointers specified by the blocked connections bundled together into an array.

/* IMP: R-45092-55768 */
# EVIDENCE-OF: R-45092-55768 If two or more such blocked connections
# have specified the same callback function, then instead of invoking
# the callback function multiple times, it is invoked once with the set
# of void* context pointers specified by the blocked connections bundled
# together into an array.

R-29466-27412-45786-34057-43817-35684-25480-06167 tcl slt th3 src

If a given call to sqlite3_unlock_notify() would put the system in a deadlocked state, then SQLITE_LOCKED is returned and no unlock-notify callback is registered.

/* IMP: R-29466-27412 */
# EVIDENCE-OF: R-29466-27412 If a given call to sqlite3_unlock_notify()
# would put the system in a deadlocked state, then SQLITE_LOCKED is
# returned and no unlock-notify callback is registered.

R-09479-17959-18929-07004-59700-09241-00688-08802 tcl slt th3 src

Indirect deadlock is also detected, so the system is also considered to be deadlocked if connection B has registered for an unlock-notify callback on the conclusion of connection C's transaction, where connection C is waiting on connection A.

/* IMP: R-09479-17959 */
# EVIDENCE-OF: R-09479-17959 Indirect deadlock is also detected, so the
# system is also considered to be deadlocked if connection B has
# registered for an unlock-notify callback on the conclusion of
# connection C's transaction, where connection C is waiting on
# connection A.

R-04813-30632-36613-23233-44977-18945-21013-25400 tcl slt th3 src

Any number of levels of indirection are allowed.

/* IMP: R-04813-30632 */
# EVIDENCE-OF: R-04813-30632 Any number of levels of indirection are
# allowed.

R-55460-47820-18774-52597-12272-16306-23027-62332 tcl slt th3 src

If there is a blocking connection, then the extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in the special "DROP TABLE/INDEX" case, the extended error code is just SQLITE_LOCKED.

/* IMP: R-55460-47820 */
# EVIDENCE-OF: R-55460-47820 If there is a blocking connection, then the
# extended error code is set to SQLITE_LOCKED_SHAREDCACHE. Otherwise, in
# the special "DROP TABLE/INDEX" case, the extended error code is just
# SQLITE_LOCKED.