/ Check-in [8fc83474]
Login

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Update the documentation for sqlite3_snapshot_cmp() to make the circumstances under which the comparison is valid clearer. Add tests for the same.
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | snapshot-cmp
Files: files | file ages | folders
SHA1: 8fc834741bf6c8a832a180795c3d6f5c3dcfcd62
User & Date: dan 2016-04-12 15:14:25
Context
2016-04-12
16:04
Add the sqlite3_snapshot_cmp() interface (available only with SQLITE_ENABLE_SNAPSHOT). check-in: 7e728965 user: drh tags: trunk
15:14
Update the documentation for sqlite3_snapshot_cmp() to make the circumstances under which the comparison is valid clearer. Add tests for the same. Closed-Leaf check-in: 8fc83474 user: dan tags: snapshot-cmp
2016-04-11
19:59
Add the sqlite3_snapshot_cmp() API. check-in: c698a21a user: dan tags: snapshot-cmp
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

8132
8133
8134
8135
8136
8137
8138
8139
8140
8141






8142
8143
8144
8145
8146
8147
8148
** 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 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. 






**
** 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,







|
|
|
>
>
>
>
>
>







8132
8133
8134
8135
8136
8137
8138
8139
8140
8141
8142
8143
8144
8145
8146
8147
8148
8149
8150
8151
8152
8153
8154
** 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,

Changes to test/snapshot.test.

364
365
366
367
368
369
370










371
372

373
374
375
376
377
378
379
...
381
382
383
384
385
386
387

388

389
390

391







392
393









394
395



396
397







398


399
400
401
402
} {1 SQLITE_ERROR}

sqlite3_snapshot_free $snapshot

#-------------------------------------------------------------------------
# The following tests investigate the sqlite3_snapshot_cmp() API.
#










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 }
................................................................................
  execsql {
    INSERT INTO t1 VALUES(10);
    COMMIT;
  }
  execsql { BEGIN ; PRAGMA application_id }
  set p2 [sqlite3_snapshot_get db main]
  execsql COMMIT



  sqlite3_snapshot_cmp $p1 $p2
} {-1}









do_test 7.1.3 {
  sqlite3_snapshot_cmp $p2 $p1









} {1}




do_test 7.1.4 {
  list [sqlite3_snapshot_cmp $p1 $p1] [sqlite3_snapshot_cmp $p2 $p2]







} {0 0}


sqlite3_snapshot_free $p1
sqlite3_snapshot_free $p2

finish_test







>
>
>
>
>
>
>
>
>
>


>







 







>

>
|
<
>

>
>
>
>
>
>
>
|
|
>
>
>
>
>
>
>
>
>
|

>
>
>
|
<
>
>
>
>
>
>
>
|
>
>




364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
...
392
393
394
395
396
397
398
399
400
401
402

403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428

429
430
431
432
433
434
435
436
437
438
439
440
441
442
} {1 SQLITE_ERROR}

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 }
................................................................................
  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