SQLite

** SQLITE_OK.
**
** If the specified database does not exist, or is not a wal mode database, 
** or the database handle does not have an open read transaction on it,
** SQLITE_ERROR is returned. If any other error occurs, for example an IO 
** error or an OOM condition, the corresponding SQLite error code is 
** returned.
**
** Each successful call to sqlite3_snapshot_get() must be matched by a call
** to sqlite3_snapshot_free() to delete the snapshot handle. Not doing so
** is a memory leak. The results of using a snapshot handle after it has 
** been deleted by sqlite3_snapshot_free() are undefined.
**
** Given a snapshot handle, the sqlite3_snapshot_open() API function may be
** used to open a read transaction on the same database snapshot that was
** being read when sqlite3_snapshot_get() was called to obtain it. The
** combination of the first two arguments to sqlite3_snapshot_open() - a
** database handle and the name (e.g. "main") of one of its attached 
** databases - must refer to the same database file as that identified by 
** the arguments passed to the sqlite3_snapshot_get() call. The database
** handle must not have an open read or write transaction on this database
** file, and must not be in auto-commit mode.
**
** An old database snapshot may only be opened if SQLite is able to 
** determine that it is still valid. The only way for an application to 
** guarantee that a snapshot remains valid is by holding an open 
** read-transaction on it or on an older snapshot of the same database 
** file. If SQLite cannot determine that the snapshot identified by the
** snapshot handle, SQLITE_BUSY_SNAPSHOT is returned.
**
** Otherwise, if the read transaction is successfully opened, SQLITE_OK is
** returned. If the named database is not in wal mode or if the database
** handle already has an open read or write transaction on it, or if the 
** database handle is in auto-commit mode, SQLITE_ERROR is returned. If
** an OOM or IO error occurs, the associated SQLite error code is returned.
*/
typedef struct sqlite3_snapshot sqlite3_snapshot;
int sqlite3_snapshot_get(sqlite3*, const char*, sqlite3_snapshot **ppSnapshot);
int sqlite3_snapshot_open(sqlite3*, const char*, sqlite3_snapshot*);
void sqlite3_snapshot_free(sqlite3_snapshot*);
int sqlite3_snapshot_open(sqlite3*, const char*, sqlite3_snapshot*);

/*
** Undo the hack that converts floating point types to integer for
** builds on processors without floating point support.
*/
#ifdef SQLITE_OMIT_FLOATING_POINT
# undef double

      mxI = i;
    }
  }
  /* There was once an "if" here. The extra "{" is to preserve indentation. */
  {
    if( (pWal->readOnly & WAL_SHM_RDONLY)==0
     && (mxReadMark<mxFrame || mxI==0)
#ifdef SQLITE_ENABLE_SNAPSHOT
     && pWal->pSnapshot==0
#endif
    ){
      for(i=1; i<WAL_NREADER; i++){
        rc = walLockExclusive(pWal, WAL_READ_LOCK(i), 1);
        if( rc==SQLITE_OK ){
          mxReadMark = pInfo->aReadMark[i] = mxFrame;
          mxI = i;
          walUnlockExclusive(pWal, WAL_READ_LOCK(i), 1);
          break;
        }else if( rc!=SQLITE_BUSY ){
          return rc;
        }
      }
    }
    if( mxI==0 ){
#ifdef SQLITE_ENABLE_SNAPSHOT
      if( pWal->pSnapshot ) return SQLITE_BUSY_SNAPSHOT;
#endif
      assert( rc==SQLITE_BUSY || (pWal->readOnly & WAL_SHM_RDONLY)!=0 );
      return rc==SQLITE_BUSY ? WAL_RETRY : SQLITE_READONLY_CANTLOCK;
    }

    rc = walLockShared(pWal, WAL_READ_LOCK(mxI));
    if( rc ){
      return rc==SQLITE_BUSY ? WAL_RETRY : rc;

  testcase( (rc&0xff)==SQLITE_IOERR );
  testcase( rc==SQLITE_PROTOCOL );
  testcase( rc==SQLITE_OK );

#ifdef SQLITE_ENABLE_SNAPSHOT
  if( rc==SQLITE_OK ){
    if( pSnapshot && memcmp(pSnapshot, &pWal->hdr, sizeof(WalIndexHdr)) ){
      /* At this point the client has a lock on an aReadMark[] slot holding
      ** a value equal to or smaller than pSnapshot->mxFrame. This client
      ** did not populate the aReadMark[] slot. pWal->hdr is populated with
      ** the wal-index header for the snapshot currently at the head of the
      ** wal file, which is different from pSnapshot.
      **
      ** The presence of the aReadMark[] slot entry makes it very likely 
      ** that either there is currently another read-transaction open on
      ** pSnapshot, or that there has been one more recently than the last
      ** checkpoint of any frames greater than pSnapshot->mxFrame was 
      ** started. There is an exception though: client 1 may have called
      ** walTryBeginRead and started to open snapshot pSnapshot, setting
      ** the aReadMark[] slot to do so. At the same time, client 2 may 
      ** have committed a new snapshot to disk and started a checkpoint.
      ** In this circumstance client 1 does not end up reading pSnapshot,
      ** but may leave the aReadMark[] slot populated.
      **
      ** The race condition above is difficult to detect. One approach would
      ** be to check the aReadMark[] slot for another client. But this is
      ** prone to false-positives from other snapshot clients. And there
      ** is no equivalent to xCheckReservedLock() for wal locks. Another
      ** approach would be to take the checkpointer lock and check that
      ** fewer than pSnapshot->mxFrame frames have been checkpointed. But
      ** that does not account for checkpointer processes that failed after
      ** checkpointing frames but before updating WalCkptInfo.nBackfill.
      ** And it would mean that this function would block on checkpointers
      ** and vice versa.
      **
      ** TODO: For now, this race condition is ignored.
      */
      volatile WalCkptInfo *pInfo = walCkptInfo(pWal);
      rc = walLockShared(pWal, WAL_READ_LOCK(0));
      if( rc==SQLITE_OK ){
        if( pInfo->nBackfill<=pSnapshot->mxFrame 
         && pSnapshot->aSalt[0]==pWal->hdr.aSalt[0]
         && pSnapshot->aSalt[1]==pWal->hdr.aSalt[1]
        ){

      assert( pWal->readLock>0 );
      assert( pInfo->aReadMark[pWal->readLock]<=pSnapshot->mxFrame );

      /* Check that the wal file has not been wrapped. Assuming it has not,
      ** overwrite pWal->hdr with *pSnapshot and set *pChanged as appropriate
      ** for opening the snapshot. Or, if the wal file has been wrapped
      ** since pSnapshot was written, return SQLITE_BUSY_SNAPSHOT. */
      if( pSnapshot->aSalt[0]==pWal->hdr.aSalt[0]
       && pSnapshot->aSalt[1]==pWal->hdr.aSalt[1]
      ){
          assert( pWal->readLock>0 );
          assert( pInfo->aReadMark[pWal->readLock]<=pSnapshot->mxFrame );
          memcpy(&pWal->hdr, pSnapshot, sizeof(WalIndexHdr));
          *pChanged = bChanged;
        }else{
          rc = SQLITE_BUSY_SNAPSHOT;
        }
        memcpy(&pWal->hdr, pSnapshot, sizeof(WalIndexHdr));
        *pChanged = bChanged;
      }else{
        rc = SQLITE_BUSY_SNAPSHOT;
      }
        walUnlockShared(pWal, WAL_READ_LOCK(0));
      }

      if( rc!=SQLITE_OK ){
        sqlite3WalEndReadTransaction(pWal);
      }
    }
  }
#endif
  return rc;

} {1 SQLITE_ERROR}
do_execsql_test 1.3.2 COMMIT

#-------------------------------------------------------------------------
# Check that a simple case works. Reuse the database created by the
# block of tests above.
#
# UPDATE: This case (2.1) no longer works. 2.2 does.
#
do_execsql_test 2.0 {
do_execsql_test 2.1.0 {
  BEGIN;
    SELECT * FROM t1;
} {1 2 3 4 5 6 7 8}

do_test 2.1 {
do_test 2.1.1 {
  set snapshot [sqlite3_snapshot_get db main]
  execsql {
    COMMIT;
    INSERT INTO t1 VALUES(9, 10);
    SELECT * FROM t1;
  }
} {1 2 3 4 5 6 7 8 9 10}

do_test 2.2 {
do_test 2.1.2 {
  execsql BEGIN
  list [catch { sqlite3_snapshot_open db main $snapshot } msg] $msg
} {1 SQLITE_BUSY_SNAPSHOT}

do_test 2.1.3 {
  sqlite3_snapshot_free $snapshot
  execsql COMMIT
} {}

do_test 2.2.0 {
  sqlite3 db2 test.db
  execsql {
    BEGIN;
      SELECT * FROM t1;
  } db2
} {1 2 3 4 5 6 7 8 9 10}

do_test 2.2.1 {
  set snapshot [sqlite3_snapshot_get db2 main]
  execsql {
    INSERT INTO t1 VALUES(11, 12);
    SELECT * FROM t1;
  }
} {1 2 3 4 5 6 7 8 9 10 11 12}

do_test 2.1.2 {
  execsql BEGIN
  sqlite3_snapshot_open db main $snapshot
  execsql {
  execsql { SELECT * FROM t1 }
} {1 2 3 4 5 6 7 8}
    SELECT * FROM t1;
  }
} {1 2 3 4 5 6 7 8 9 10}

do_test 2.3 {
do_test 2.1.3 {
  sqlite3_snapshot_free $snapshot
  execsql COMMIT
  execsql COMMIT db2
  db2 close
} {}

#-------------------------------------------------------------------------
# Check some errors in sqlite3_snapshot_open(). It is an error if:
#
#   1) the db is in auto-commit mode,
#   2) the db has an open (read or write) transaction,