From: drh <>
Date: Tue, 4 Oct 2022 14:50:46 +0000 (+0000)
Subject: Attempt to clarify the operation of the xLock and xUnlock VFS I/O methods.
X-Git-Tag: version-3.40.0~179
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=2eca06141feae3d241776e59b798b4aa1ce128b6;p=thirdparty%2Fsqlite.git
Attempt to clarify the operation of the xLock and xUnlock VFS I/O methods.
Assert() statements added to prove that they behave as the documentation says.
FossilOrigin-Name: 3efa811251d4510a074231a1e0b667783cc5f90777466b9dcae675cd9892b423
---
diff --git a/manifest b/manifest
index d690941a1f..60a41be11a 100644
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Change\sthe\sname\sof\sthe\sautoconf-generated\sconfiguration\sfile\sfrom\s"config.h"\nto\s"sqlite_cfg.h"\sto\swork\saround\sa\sbug\sin\sa\sdependency\schecker,\sreported\nin\s[https://twitter.com/josecastillo/status/1577136108097314816|a\stweet\sfrom\sJose\sCastillo].
-D 2022-10-04T10:35:10.544
+C Attempt\sto\sclarify\sthe\soperation\sof\sthe\sxLock\sand\sxUnlock\sVFS\sI/O\smethods.\nAssert()\sstatements\sadded\sto\sprove\sthat\sthey\sbehave\sas\sthe\sdocumentation\ssays.
+D 2022-10-04T14:50:46.626
F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
F LICENSE.md df5091916dbb40e6e9686186587125e1b2ff51f022cc334e886c19a0e9982724
@@ -520,7 +520,7 @@ F spec.template 86a4a43b99ebb3e75e6b9a735d5fd293a24e90ca
F sqlite.pc.in 42b7bf0d02e08b9e77734a47798d1a55a9e0716b
F sqlite3.1 fc7ad8990fc8409983309bb80de8c811a7506786
F sqlite3.pc.in 48fed132e7cb71ab676105d2a4dc77127d8c1f3a
-F sqlite_cfg.h.in baf2e409c63d4e7a765e17769b6ff17c5a82bbd9cbf1e284fd2e4cefaff3fcf2 w config.h.in
+F sqlite_cfg.h.in baf2e409c63d4e7a765e17769b6ff17c5a82bbd9cbf1e284fd2e4cefaff3fcf2
F src/alter.c 0390ca1d69ec3626cfa9f153114b7ab233e6b2bada6a9eb91361ed385fe90deb
F src/analyze.c aabdf3769c7fd9954a8ec508eb7041ae174b66f88d12c47199fabbea9a646467
F src/attach.c 4431f82f0247bf3aaf91589acafdff77d1882235c95407b36da1585c765fbbc8
@@ -568,7 +568,7 @@ F src/mutex_noop.c 9d4309c075ba9cc7249e19412d3d62f7f94839c4
F src/mutex_unix.c dd2b3f1cc1863079bc1349ac0fec395a500090c4fe4e11ab775310a49f2f956d
F src/mutex_w32.c caa50e1c0258ac4443f52e00fe8aaea73b6d0728bd8856bedfff822cae418541
F src/notify.c 89a97dc854c3aa62ad5f384ef50c5a4a11d70fcc69f86de3e991573421130ed6
-F src/os.c 0eb831ba3575af5277e47f4edd14fdfc90025c67eb25ce5cda634518d308d4e9
+F src/os.c 81c9c1c52eab711e27e33fd51fe5788488d3a02bc1a71439857abbee5d0d2c97
F src/os.h 1ff5ae51d339d0e30d8a9d814f4b8f8e448169304d83a7ed9db66a65732f3e63
F src/os_common.h b2f4707a603e36811d9b1a13278bffd757857b85
F src/os_setup.h 0dbaea40a7d36bf311613d31342e0b99e2536586
@@ -590,7 +590,7 @@ F src/resolve.c efea4e5fbecfd6d0a9071b0be0d952620991673391b6ffaaf4c277b0bb674633
F src/rowset.c ba9515a922af32abe1f7d39406b9d35730ed65efab9443dc5702693b60854c92
F src/select.c bb18acf4eded647fef88d4d543c673874dbebff516fbeba90a85e6c13f2a58cd
F src/shell.c.in e7e7c2c69ae86c5ee9e8ad66227203d46ff6dce8700a1b1dababff01c71d33df
-F src/sqlite.h.in 3f4695457fcb41ea8a44c6d09fc2a591bbeda44b13bda86618f3ce0071bbca7c
+F src/sqlite.h.in bcc51bb43c54676dccbad07051c6d463212707f50363d64f1831440749e91ddb
F src/sqlite3.rc 5121c9e10c3964d5755191c80dd1180c122fc3a8
F src/sqlite3ext.h a988810c9b21c0dc36dc7a62735012339dc76fc7ab448fb0792721d30eacb69d
F src/sqliteInt.h 1d27d00dcaafed614d6ed8738d6c41a81acf12fe50fe4c677427b1c56d8a81da
@@ -2000,8 +2000,8 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P d7c2be6bdc3402e5a339d0f7b76d2c25f3a444dcbf54a77c1ccb790d1195a7cf
-R 4713eb8f98a8aeab7d0d3163e5e46206
+P 897e187cad981126fc5f6ea8e382e937825af10b0c9589b0a23b9fbaa4ca58b8
+R e2ac55c08c3f1d2d33e5a2d4f6cdf937
U drh
-Z cc19c5c21171ef2d2de636f9d251ad05
+Z d8fbc7d6453f3413769ceb23c01d9355
# Remove this line to create a well-formed Fossil manifest.
diff --git a/manifest.uuid b/manifest.uuid
index 81b40ebe86..f7cb13b05b 100644
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-897e187cad981126fc5f6ea8e382e937825af10b0c9589b0a23b9fbaa4ca58b8
\ No newline at end of file
+3efa811251d4510a074231a1e0b667783cc5f90777466b9dcae675cd9892b423
\ No newline at end of file
diff --git a/src/os.c b/src/os.c
index 13c9abcab4..e2914e03c0 100644
--- a/src/os.c
+++ b/src/os.c
@@ -106,9 +106,11 @@ int sqlite3OsFileSize(sqlite3_file *id, i64 *pSize){
}
int sqlite3OsLock(sqlite3_file *id, int lockType){
DO_OS_MALLOC_TEST(id);
+ assert( lockType>=SQLITE_LOCK_SHARED && lockType<=SQLITE_LOCK_EXCLUSIVE );
return id->pMethods->xLock(id, lockType);
}
int sqlite3OsUnlock(sqlite3_file *id, int lockType){
+ assert( lockType==SQLITE_LOCK_NONE || lockType==SQLITE_LOCK_SHARED );
return id->pMethods->xUnlock(id, lockType);
}
int sqlite3OsCheckReservedLock(sqlite3_file *id, int *pResOut){
diff --git a/src/sqlite.h.in b/src/sqlite.h.in
index df61f3c196..03a3e5cc01 100644
--- a/src/sqlite.h.in
+++ b/src/sqlite.h.in
@@ -670,13 +670,17 @@ int sqlite3_exec(
**
** SQLite uses one of these integer values as the second
** argument to calls it makes to the xLock() and xUnlock() methods
-** of an [sqlite3_io_methods] object.
+** of an [sqlite3_io_methods] object. These values are ordered from
+** lest restrictive to most restrictive.
+**
+** The argument to xLock() is always SHARED or higher. The argument to
+** xUnlock is either SHARED or NONE.
*/
-#define SQLITE_LOCK_NONE 0
-#define SQLITE_LOCK_SHARED 1
-#define SQLITE_LOCK_RESERVED 2
-#define SQLITE_LOCK_PENDING 3
-#define SQLITE_LOCK_EXCLUSIVE 4
+#define SQLITE_LOCK_NONE 0 /* xUnlock() only */
+#define SQLITE_LOCK_SHARED 1 /* xLock() or xUnlock() */
+#define SQLITE_LOCK_RESERVED 2 /* xLock() only */
+#define SQLITE_LOCK_PENDING 3 /* xLock() only */
+#define SQLITE_LOCK_EXCLUSIVE 4 /* xLock() only */
/*
** CAPI3REF: Synchronization Type Flags
@@ -754,7 +758,14 @@ struct sqlite3_file {
** [SQLITE_LOCK_PENDING], or
** [SQLITE_LOCK_EXCLUSIVE].
**
-** xLock() increases the lock. xUnlock() decreases the lock.
+** xLock() upgrades the database file lock. In other words, xLock() moves the
+** database file lock in the direction NONE toward EXCLUSIVE. The argument to
+** xLock() is always on of SHARED, RESERVED, PENDING, or EXCLUSIVE, never
+** SQLITE_LOCK_NONE. If the database file lock is already at or above the
+** requested lock, then the call to xLock() is a no-op.
+** xUnlock() downgrades the database file lock to either SHARED or NONE.
+* If the lock is already at or below the requested lock state, then the call
+** to xUnlock() is a no-op.
** The xCheckReservedLock() method checks whether any database connection,
** either in this process or in some other process, is holding a RESERVED,
** PENDING, or EXCLUSIVE lock on the file. It returns true
@@ -859,9 +870,8 @@ struct sqlite3_io_methods {
** opcode causes the xFileControl method to write the current state of
** the lock (one of [SQLITE_LOCK_NONE], [SQLITE_LOCK_SHARED],
** [SQLITE_LOCK_RESERVED], [SQLITE_LOCK_PENDING], or [SQLITE_LOCK_EXCLUSIVE])
-** into an integer that the pArg argument points to. This capability
-** is used during testing and is only available when the SQLITE_TEST
-** compile-time option is used.
+** into an integer that the pArg argument points to.
+** This capability is only available if SQLite is compiled with [SQLITE_DEBUG].
**
** [[SQLITE_FCNTL_SIZE_HINT]]
** The [SQLITE_FCNTL_SIZE_HINT] opcode is used by SQLite to give the VFS