Help Center
/
Help Center›AfxNova›CSQLite Class

CSQLiteStmt.UnlockNotifymethod

Registers a callback that SQLite will invoke when the connection currently holding the required lock relinquishes it.

DatabasesmethodCSQLite.incdoc-orphan
No implementation located. This member is documented, but the source scan found no matching declaration. It is likely declared in a header this scan does not resolve, or provided by a macro.

Syntax

FUNCTION UnlockNotify (BYVAL pNotifyCallback AS ANY PTR, BYVAL pNotifyArg AS ANY PTR) AS LONG

Parameters

NameDescription
pNotifyCallbackPointer to the callback function.
pNotifyArgData that is passed through the second parameter to the callback function.

Description

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. This API may be used to register a callback that SQLite will invoke when the connection currently holding the required lock relinquishes it. This API is only available if the library was compiled with the SQLITE_ENABLE_UNLOCK_NOTIFY C-preprocessor symbol defined.

Return value

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

Remarks

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

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. After an application receives an SQLITE_LOCKED error, it may call the UnlockNotify 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. The callback is invoked from within the Step_ or Close call that concludes the blocking connections transaction.

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

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.

There may be at most one unlock-notify callback registered by a blocked connection. If UnlockNotify is called when the blocked connection already has a registered unlock-notify callback, then the new callback replaces the old. If UnlockNotify is called with a NULL pointer as its second argument, then any existing unlock-notify callback is canceled. The blocked connections unlock-notify callback may also be canceled by closing the blocked connection using Close.

The unlock-notify callback is not reentrant. If an application invokes any sqlite3_xxx API functions from within an unlock-notify callback, a crash or deadlock may be the result.

Reference

  • Include file CSQLite.inc
  • Documented in Databases/CSQLite Class.md
  • Topic: CSQLite Class