From: dan <dan@noemail.net>
Date: Tue, 12 Apr 2016 15:14:25 +0000 (+0000)
Subject: Update the documentation for sqlite3_snapshot_cmp() to make the circumstances under... 
X-Git-Tag: version-3.13.0~97^2
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=745be369c799ab98c8c6798d92ec4f295bd54de9;p=thirdparty%2Fsqlite.git

Update the documentation for sqlite3_snapshot_cmp() to make the circumstances under which the comparison is valid clearer. Add tests for the same.

FossilOrigin-Name: 8fc834741bf6c8a832a180795c3d6f5c3dcfcd62
---

diff --git a/manifest b/manifest
index 70a209bfeb..b6732de4b4 100644
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Add\sthe\ssqlite3_snapshot_cmp()\sAPI.
-D 2016-04-11T19:59:52.090
+C Update\sthe\sdocumentation\sfor\ssqlite3_snapshot_cmp()\sto\smake\sthe\scircumstances\sunder\swhich\sthe\scomparison\sis\svalid\sclearer.\sAdd\stests\sfor\sthe\ssame.
+D 2016-04-12T15:14:25.762
 F Makefile.in eba680121821b8a60940a81454316f47a341487a
 F Makefile.linux-gcc 7bc79876b875010e8c8f9502eb935ca92aa3c434
 F Makefile.msc 1f123a0757f6f04f0341accb46457e116817159a
@@ -377,7 +377,7 @@ F src/resolve.c b8f7174e5f8c33c44ded3a25a973d0bb89228c20
 F src/rowset.c 9fe4b3ad7cc00944386bb600233d8f523de07a6e
 F src/select.c d9b8628acb98f1a38921888d823a6b70c7a7774b
 F src/shell.c b7922fa264f8c8d72a5ec6dd0b091e15a93c4de5
-F src/sqlite.h.in 1ce5ab46279c809302078a10fca0c8107a88504e
+F src/sqlite.h.in 64eb70a3b309751bebf73a5552a51244f68f0ea5
 F src/sqlite3.rc 5121c9e10c3964d5755191c80dd1180c122fc3a8
 F src/sqlite3ext.h 98f72cbfe00169c39089115427d06ea05fe4b4a2
 F src/sqliteInt.h b3744b29555b83054f315f62d61b3a6558fa9e1c
@@ -1065,7 +1065,7 @@ F test/skipscan2.test d1d1450952b7275f0b0a3a981f0230532743951a
 F test/skipscan3.test ec5bab3f81c7038b43450e7b3062e04a198bdbb5
 F test/skipscan5.test 67817a4b6857c47e0e33ba3e506da6f23ef68de2
 F test/skipscan6.test 5866039d03a56f5bd0b3d172a012074a1d90a15b
-F test/snapshot.test 4488cd49f82095b07a64b63e35ca5f07ae3cf6ff
+F test/snapshot.test 3adc4ef09d407b501f899a6c329bdf45dc725c1b
 F test/snapshot_fault.test 062ff0438a074978d45e9f9a92e7ad459b74ee73
 F test/soak.test 0b5b6375c9f4110c828070b826b3b4b0bb65cd5f
 F test/softheap1.test 843cd84db9891b2d01b9ab64cef3e9020f98d087
@@ -1482,10 +1482,7 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
 F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
 F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P 9efe2265b1e70172778d333c5b9d9a76095427ab
-R 90e72a50c886c4c06c826581c1212ad7
-T *branch * snapshot-cmp
-T *sym-snapshot-cmp *
-T -sym-trunk *
+P c698a21af740ca1019c3a771fb83e569cd6bf23e
+R 1df0b51d3ec92c57900ed6ffc629e927
 U dan
-Z 6bc91ca9d3bb5c1b79f55141c1c596ee
+Z 0bd02cd207722d1ba1dc6f0818f7fd4a
diff --git a/manifest.uuid b/manifest.uuid
index d2b5c07f05..d0089f5647 100644
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-c698a21af740ca1019c3a771fb83e569cd6bf23e
\ No newline at end of file
+8fc834741bf6c8a832a180795c3d6f5c3dcfcd62
\ No newline at end of file
diff --git a/src/sqlite.h.in b/src/sqlite.h.in
index f5ccaf40e1..d50d826b41 100644
--- a/src/sqlite.h.in
+++ b/src/sqlite.h.in
@@ -8136,9 +8136,15 @@ SQLITE_EXPERIMENTAL void sqlite3_snapshot_free(sqlite3_snapshot*);
 ** of two valid snapshot handles. 
 **
 ** If the two snapshot handles are not associated with the same database 
-** file, the results are undefined. If either of the snapshot handles
-** is no longer valid because the database snapshot they refer to has been
-** destroyed by a checkpoint, the results are undefined. 
+** file, the result of the comparison is undefined. 
+**
+** Additionally, the result of the comparison is only valid if both of the
+** snapshot handles were obtained by calling sqlite3_snapshot_get() since the
+** last time the wal file was deleted. The wal file is deleted when the
+** database is changed back to rollback mode or when the number of database
+** clients drops to zero. If either snapshot handle was obtained before the 
+** wal file was last deleted, the value returned by this function 
+** is undefined.
 **
 ** Otherwise, this API returns a negative value if P1 refers to an older
 ** snapshot than P2, zero if the two handles refer to the same database
diff --git a/test/snapshot.test b/test/snapshot.test
index 5f6c4e1e4f..6dff11bbb9 100644
--- a/test/snapshot.test
+++ b/test/snapshot.test
@@ -368,8 +368,19 @@ sqlite3_snapshot_free $snapshot
 #-------------------------------------------------------------------------
 # The following tests investigate the sqlite3_snapshot_cmp() API.
 #
+
+# Compare snapshots $p1 and $p2, checking that the result is $r.
+#
+proc do_snapshot_cmp_test {tn p1 p2 r} {
+  uplevel [list do_test $tn.1 [list sqlite3_snapshot_cmp $p1 $p2] $r]
+  uplevel [list do_test $tn.2 [list sqlite3_snapshot_cmp $p2 $p1] [expr $r*-1]]
+  uplevel [list do_test $tn.3 [list sqlite3_snapshot_cmp $p1 $p1] 0]
+  uplevel [list do_test $tn.4 [list sqlite3_snapshot_cmp $p2 $p2] 0]
+}
+
 catch { db2 close }
 reset_db
+
 do_execsql_test 7.1 {
   PRAGMA journal_mode = wal;
   CREATE TABLE t1(x);
@@ -385,17 +396,46 @@ do_test 7.1.2 {
   execsql { BEGIN ; PRAGMA application_id }
   set p2 [sqlite3_snapshot_get db main]
   execsql COMMIT
+} {}
+
+do_snapshot_cmp_test 7.1.3 $p1 $p2 -1
+sqlite3_snapshot_free $p1
+sqlite3_snapshot_free $p2
+
+do_execsql_test 7.2.1 {
+  INSERT INTO t1 VALUES(11);
+  INSERT INTO t1 VALUES(12);
+  INSERT INTO t1 VALUES(13);
+  BEGIN; 
+    PRAGMA application_id;
+} {0}
+do_test 7.2.2 {
+  set p1 [sqlite3_snapshot_get db main]
+  execsql {
+    COMMIT;
+    INSERT INTO t1 VALUES(14);
+    PRAGMA wal_checkpoint;
+    BEGIN;
+      PRAGMA application_id;
+  }
+  set p2 [sqlite3_snapshot_get db main]
+  execsql COMMIT
+} {}
 
-  sqlite3_snapshot_cmp $p1 $p2
-} {-1}
+do_snapshot_cmp_test 7.2.3 $p1 $p2 -1
+sqlite3_snapshot_free $p2
 
-do_test 7.1.3 {
-  sqlite3_snapshot_cmp $p2 $p1
-} {1}
+do_test 7.3.1 {
+  execsql {
+    INSERT INTO t1 VALUES(14);
+    BEGIN;
+      PRAGMA application_id;
+  }
+  set p2 [sqlite3_snapshot_get db main]
+  execsql COMMIT
+} {}
 
-do_test 7.1.4 {
-  list [sqlite3_snapshot_cmp $p1 $p1] [sqlite3_snapshot_cmp $p2 $p2]
-} {0 0}
+do_snapshot_cmp_test 7.3.2 $p1 $p2 -1
 sqlite3_snapshot_free $p1
 sqlite3_snapshot_free $p2