Add the sqlite3_snapshot_cmp() interface (available only with

SQLITE_ENABLE_SNAPSHOT).

FossilOrigin-Name: 7e7289655185e7643ead6d685922528bc4d9e0ae

manifest

@@ -1,5 +1,5 @@
-C Update\sthe\sheader\scomment\son\sthe\smemjournal.c\sfile.\s\sNo\scode\schanges.
-D 2016-04-12T11:58:18.868
+C Add\sthe\ssqlite3_snapshot_cmp()\sinterface\s(available\sonly\swith\nSQLITE_ENABLE_SNAPSHOT).
+D 2016-04-12T16:04:07.576
 F Makefile.in eba680121821b8a60940a81454316f47a341487a
 F Makefile.linux-gcc 7bc79876b875010e8c8f9502eb935ca92aa3c434
 F Makefile.msc 71b8b16cf9393f68e2e2035486ca104872558836
@@ -377,7 +377,7 @@ F src/resolve.c b8f7174e5f8c33c44ded3a25a973d0bb89228c20
 F src/rowset.c 9fe4b3ad7cc00944386bb600233d8f523de07a6e
 F src/select.c a07e6022e2b559f3c2ec80442472c5965fa7a3fc
 F src/shell.c b7922fa264f8c8d72a5ec6dd0b091e15a93c4de5
-F src/sqlite.h.in c8f41612dc1a9b5212a891e1b65a5f589b8b884a
+F src/sqlite.h.in 64eb70a3b309751bebf73a5552a51244f68f0ea5
 F src/sqlite3.rc 5121c9e10c3964d5755191c80dd1180c122fc3a8
 F src/sqlite3ext.h 98f72cbfe00169c39089115427d06ea05fe4b4a2
 F src/sqliteInt.h b3744b29555b83054f315f62d61b3a6558fa9e1c
@@ -385,7 +385,7 @@ F src/sqliteLimit.h c0373387c287c8d0932510b5547ecde31b5da247
 F src/status.c 70912d7be68e9e2dbc4010c93d344af61d4c59ba
 F src/table.c 5226df15ab9179b9ed558d89575ea0ce37b03fc9
 F src/tclsqlite.c 56569acc73d36e836b64aefecbbb709a92ba0077
-F src/test1.c 7187b7e924bfc97780e6fd2a40dad94a32bddca0
+F src/test1.c 457c601302b8a0f5960dffd17b6a2877603841dd
 F src/test2.c 5586f43fcd9a1be0830793cf9d354082c261b25b
 F src/test3.c a8887dabbbee3059af338f20d290084a63ed1b0f
 F src/test4.c d168f83cc78d02e8d35567bb5630e40dcd85ac1e
@@ -452,7 +452,7 @@ F src/vdbesort.c 307460bfa4de4d1c3901fcd42089159131e34062
 F src/vdbetrace.c f75c5455d8cf389ef86a8bfdfd3177e0e3692484
 F src/vtab.c 23b6cdfa996152d43b390504ed4a942c8caf3a00
 F src/vxworks.h d2988f4e5a61a4dfe82c6524dd3d6e4f2ce3cdb9
-F src/wal.c 10deb6b43887662691e5f53d10b3c171c401169b
+F src/wal.c 4db22ed7e77bcf672b1a685d6ddeffba8d5be302
 F src/wal.h 2f7c831cf3b071fa548bf2d5cac640846a7ff19c
 F src/walker.c 0f142b5bd3ed2041fc52d773880748b212e63354
 F src/where.c 24ab561466d92d313747c04edb1a36a7af8663be
@@ -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 9ed24c792fb05382814258daf68b2256f23de57f
+F test/snapshot.test 3adc4ef09d407b501f899a6c329bdf45dc725c1b
 F test/snapshot_fault.test 062ff0438a074978d45e9f9a92e7ad459b74ee73
 F test/soak.test 0b5b6375c9f4110c828070b826b3b4b0bb65cd5f
 F test/softheap1.test 843cd84db9891b2d01b9ab64cef3e9020f98d087
@@ -1482,7 +1482,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 e2c4995bf1099cc02bcb1dc4a4631f06a870d171
-R 2e4cf3acc4cd7fa1ae0c658360dca721
+P 07f10deabb0f4207408142541e3913d638dfcdeb 8fc834741bf6c8a832a180795c3d6f5c3dcfcd62
+R 5656733bddcb2f7451211326ac2ed136
+T +closed 8fc834741bf6c8a832a180795c3d6f5c3dcfcd62
 U drh
-Z ca7267cbdba15c8e817fe9239b1f31a1
+Z b8985dfa1dcfaa5a463be54da15766b9

manifest.uuid

@@ -1 +1 @@
-07f10deabb0f4207408142541e3913d638dfcdeb
+7e7289655185e7643ead6d685922528bc4d9e0ae

src/sqlite.h.in

@@ -8128,6 +8128,33 @@ SQLITE_EXPERIMENTAL int sqlite3_snapshot_open(
 */
 SQLITE_EXPERIMENTAL void sqlite3_snapshot_free(sqlite3_snapshot*);
 
+/*
+** CAPI3REF: Compare the ages of two snapshot handles.
+** EXPERIMENTAL
+**
+** The sqlite3_snapshot_cmp(P1, P2) interface is used to compare the ages
+** of two valid snapshot handles. 
+**
+** If the two snapshot handles are not associated with the same database 
+** 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
+** snapshot, and a positive value if P1 is a newer snapshot than P2.
+*/
+SQLITE_EXPERIMENTAL int sqlite3_snapshot_cmp(
+  sqlite3_snapshot *p1,
+  sqlite3_snapshot *p2
+);
+
 /*
 ** Undo the hack that converts floating point types to integer for
 ** builds on processors without floating point support.

src/test1.c

@@ -2359,6 +2359,31 @@ static int test_snapshot_free(
 }
 #endif /* SQLITE_ENABLE_SNAPSHOT */
 
+#ifdef SQLITE_ENABLE_SNAPSHOT
+/*
+** Usage: sqlite3_snapshot_cmp SNAPSHOT1 SNAPSHOT2
+*/
+static int test_snapshot_cmp(
+  void * clientData,
+  Tcl_Interp *interp,
+  int objc,
+  Tcl_Obj *CONST objv[]
+){
+  int res;
+  sqlite3_snapshot *p1;
+  sqlite3_snapshot *p2;
+  if( objc!=3 ){
+    Tcl_WrongNumArgs(interp, 1, objv, "SNAPSHOT1 SNAPSHOT2");
+    return TCL_ERROR;
+  }
+  p1 = (sqlite3_snapshot*)sqlite3TestTextToPtr(Tcl_GetString(objv[1]));
+  p2 = (sqlite3_snapshot*)sqlite3TestTextToPtr(Tcl_GetString(objv[2]));
+  res = sqlite3_snapshot_cmp(p1, p2);
+  Tcl_SetObjResult(interp, Tcl_NewIntObj(res));
+  return TCL_OK;
+}
+#endif /* SQLITE_ENABLE_SNAPSHOT */
+
 /*
 ** Usage:  sqlite3_next_stmt  DB  STMT
 **
@@ -7249,6 +7274,7 @@ int Sqlitetest1_Init(Tcl_Interp *interp){
      { "sqlite3_snapshot_get", test_snapshot_get, 0 },
      { "sqlite3_snapshot_open", test_snapshot_open, 0 },
      { "sqlite3_snapshot_free", test_snapshot_free, 0 },
+     { "sqlite3_snapshot_cmp", test_snapshot_cmp, 0 },
 #endif
   };
   static int bitmask_size = sizeof(Bitmask)*8;

src/wal.c

@@ -3399,6 +3399,23 @@ int sqlite3WalSnapshotGet(Wal *pWal, sqlite3_snapshot **ppSnapshot){
 void sqlite3WalSnapshotOpen(Wal *pWal, sqlite3_snapshot *pSnapshot){
   pWal->pSnapshot = (WalIndexHdr*)pSnapshot;
 }
+
+/* 
+** Return a +ve value if snapshot p1 is newer than p2. A -ve value if
+** p1 is older than p2 and zero if p1 and p2 are the same snapshot.
+*/
+int sqlite3_snapshot_cmp(sqlite3_snapshot *p1, sqlite3_snapshot *p2){
+  WalIndexHdr *pHdr1 = (WalIndexHdr*)p1;
+  WalIndexHdr *pHdr2 = (WalIndexHdr*)p2;
+
+  /* aSalt[0] is a copy of the value stored in the wal file header. It
+  ** is incremented each time the wal file is restarted.  */
+  if( pHdr1->aSalt[0]<pHdr2->aSalt[0] ) return -1;
+  if( pHdr1->aSalt[0]>pHdr2->aSalt[0] ) return +1;
+  if( pHdr1->mxFrame<pHdr2->mxFrame ) return -1;
+  if( pHdr1->mxFrame>pHdr2->mxFrame ) return +1;
+  return 0;
+}
 #endif /* SQLITE_ENABLE_SNAPSHOT */
 
 #ifdef SQLITE_ENABLE_ZIPVFS

test/snapshot.test

@@ -365,4 +365,78 @@ do_test 6.5 {
 
 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);
+} wal
+
+do_test 7.1.2 {
+  execsql { BEGIN ; PRAGMA application_id }
+  set p1 [sqlite3_snapshot_get db main]
+  execsql {
+    INSERT INTO t1 VALUES(10);
+    COMMIT;
+  }
+  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
+} {}
+
+do_snapshot_cmp_test 7.2.3 $p1 $p2 -1
+sqlite3_snapshot_free $p2
+
+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_snapshot_cmp_test 7.3.2 $p1 $p2 -1
+sqlite3_snapshot_free $p1
+sqlite3_snapshot_free $p2
+
 finish_test