Snapshot documentation updates. Comment changes only - no changes to code.

FossilOrigin-Name: ef51a398a04963508389ffe2f9d8359c1ec48261

manifest

@@ -1,5 +1,5 @@
-C Update\sthe\ssqlite3_snapshot_get()\sAPI\sso\sthat\sif\sthe\scaller\sdoes\snot\shave\san\sopen\sread\stransaction\son\sthe\snamed\sdatabase,\sone\sis\sautomatically\sopened.
+C Snapshot\sdocumentation\supdates.\s\sComment\schanges\sonly\s-\sno\schanges\sto\scode.
-D 2015-12-10T20:03:08.672
+D 2015-12-10T22:48:22.684
 F Makefile.in 28bcd6149e050dff35d4dcfd97e890cd387a499d
 F Makefile.linux-gcc 7bc79876b875010e8c8f9502eb935ca92aa3c434
 F Makefile.msc e8fdca1cb89a1b58b5f4d3a130ea9a3d28cb314d
@@ -341,7 +341,7 @@ F src/resolve.c a83b41104e6ff69855d03cd0aaa09e93927ec39f
 F src/rowset.c eccf6af6d620aaa4579bd3b72c1b6395d9e9fa1e
 F src/select.c f8fded11fc443a9f5a73cc5db069d06b34460e2f
 F src/shell.c abbc74ea43dbf2f306ea18282d666683fb5efab2
-F src/sqlite.h.in fa2c9d85cb144fad389864f9e40c4f59336d31ed
+F src/sqlite.h.in e24a1d2e36970ca46beb8002623e1c73eab32063
 F src/sqlite3.rc 992c9f5fb8285ae285d6be28240a7e8d3a7f2bad
 F src/sqlite3ext.h dfbe62ffd95b99afe2140d8c35b180d11924072d
 F src/sqliteInt.h 5caacf37a776f9d6178e519cb0b5248ca22a3828
@@ -415,7 +415,7 @@ F src/vdbesort.c a7ec02da4494c59dfd071126dd3726be5a11459d
 F src/vdbetrace.c 8befe829faff6d9e6f6e4dee5a7d3f85cc85f1a0
 F src/vtab.c 2a8b44aa372c33f6154208e7a7f6c44254549806
 F src/vxworks.h c18586c8edc1bddbc15c004fa16aeb1e1342b4fb
-F src/wal.c 94576d273e7feeae598188ebec641906a5b93a2f
+F src/wal.c 4ecd256ad59675472fbf211001b511cb31877a74
 F src/wal.h 907943dfdef10b583e81906679a347e0ec6f1b1b
 F src/walker.c 2e14d17f592d176b6dc879c33fbdec4fbccaa2ba
 F src/where.c b18edbb9e5afabb77f4f27550c471c5c824e0fe7
@@ -1410,7 +1410,7 @@ F tool/vdbe_profile.tcl 246d0da094856d72d2c12efec03250d71639d19f
 F tool/warnings-clang.sh f6aa929dc20ef1f856af04a730772f59283631d4
 F tool/warnings.sh 48bd54594752d5be3337f12c72f28d2080cb630b
 F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f
-P f3b743623a4501833478c8a86c0922931955aeb6
+P b9c90f10297d8516a661449e8af898e682c930aa
-R 50bb5d50d586d96f69cac8095fa25e56
+R 359f52ff04c40d68d5a15fc7ff658a21
-U dan
+U drh
-Z 07077a92d084d80e6cdd7a283dbdc283
+Z f10084cbd288f6e41be166b6d28c4cd6

manifest.uuid

@@ -1 +1 @@
-b9c90f10297d8516a661449e8af898e682c930aa
+ef51a398a04963508389ffe2f9d8359c1ec48261

src/sqlite.h.in

@@ -4405,8 +4405,8 @@ unsigned int sqlite3_value_subtype(sqlite3_value*);
 ** previously obtained from [sqlite3_value_dup()].  ^If V is a NULL pointer
 ** then sqlite3_value_free(V) is a harmless no-op.
 */
-SQLITE_EXPERIMENTAL sqlite3_value *sqlite3_value_dup(const sqlite3_value*);
+sqlite3_value *sqlite3_value_dup(const sqlite3_value*);
-SQLITE_EXPERIMENTAL void sqlite3_value_free(sqlite3_value*);
+void sqlite3_value_free(sqlite3_value*);
 
 /*
 ** CAPI3REF: Obtain Aggregate Function Context
@@ -7851,85 +7851,109 @@ void sqlite3_stmt_scanstatus_reset(sqlite3_stmt*);
 /*
 ** CAPI3REF: Flush caches to disk mid-transaction
 **
-** If a write-transaction is open when this function is called, any dirty
+** ^If a write-transaction is open on [database connection] D when the
+** [sqlite3_db_cacheflush(D)] interface invoked, any dirty
 ** pages in the pager-cache that are not currently in use are written out 
 ** to disk. A dirty page may be in use if a database cursor created by an
 ** active SQL statement is reading from it, or if it is page 1 of a database
-** file (page 1 is always "in use"). Dirty pages are flushed for all
+** file (page 1 is always "in use").  ^The [sqlite3_db_cacheflush(D)]
-** databases - "main", "temp" and any attached databases.
+** interface flushes caches for all schemas - "main", "temp", and
+** any [attached] databases.
 **
-** If this function needs to obtain extra database locks before dirty pages 
+** ^If this function needs to obtain extra database locks before dirty pages 
-** can be flushed to disk, it does so. If said locks cannot be obtained 
+** can be flushed to disk, it does so. ^If those locks cannot be obtained 
 ** immediately and there is a busy-handler callback configured, it is invoked
-** in the usual manner. If the required lock still cannot be obtained, then
+** in the usual manner. ^If the required lock still cannot be obtained, then
 ** the database is skipped and an attempt made to flush any dirty pages
-** belonging to the next (if any) database. If any databases are skipped
+** belonging to the next (if any) database. ^If any databases are skipped
 ** because locks cannot be obtained, but no other error occurs, this
 ** function returns SQLITE_BUSY.
 **
-** If any other error occurs while flushing dirty pages to disk (for
+** ^If any other error occurs while flushing dirty pages to disk (for
 ** example an IO error or out-of-memory condition), then processing is
-** abandoned and an SQLite error code returned to the caller immediately.
+** abandoned and an SQLite [error code] is returned to the caller immediately.
 **
-** Otherwise, if no error occurs, SQLITE_OK is returned.
+** ^Otherwise, if no error occurs, [sqlite3_db_cacheflush()] returns SQLITE_OK.
 **
-** This function does not set the database handle error code or message
+** ^This function does not set the database handle error code or message
-** returned by the sqlite3_errcode() and sqlite3_errmsg() functions.
+** returned by the [sqlite3_errcode()] and [sqlite3_errmsg()] functions.
 */
 int sqlite3_db_cacheflush(sqlite3*);
 
 /*
-** CAPI3REF: Open old database snapshots.
+** CAPI3REF: Database Snapshot
+** KEYWORDS: {snapshot}
+** EXPERIMENTAL
 **
-** The second argument passed to sqlite3_snapshot_get() must be the name
+** An instance of the snapshot object records the state of a [WAL mode]
-** of a database file attached to the database handle passed as the first.
+** database for some specific point in history.
-** The database handle must not have an open write transaction on the named 
-** database, which must be in wal mode. If the database handle does not
-** have an open read transaction on the named file, this function opens
-** one.
 **
-** If successful, sqlite3_snapshot_get() sets *ppSnapshot to point to a new
+** In [WAL mode], multiple [database connections] that are open on the
-** snapshot handle that may be used with sqlite3_snapshot_open() and returns
+** same database file can each be reading a different historical version
-** SQLITE_OK.
+** of the database file.  When a [database connection] begins a read
+** transaction, that connection sees an unchanging copy of the database
+** as it existed for the point in time when the transaction first started.
+** Subsequent changes to the database from other connections are not seen
+** by the reader until a new read transaction is started.
 **
-** If the specified database does not exist, or is not a wal mode database, 
+** The sqlite3_snapshot object records state information about an historical
-** or the database handle does not have an open read transaction on it,
+** version of the database file so that it is possible to later open a new read
-** SQLITE_ERROR is returned. If any other error occurs, for example an IO 
+** transaction that sees that historical version of the database rather than
-** error or an OOM condition, the corresponding SQLite error code is 
+** the most recent version.
-** returned.
 **
-** Each successful call to sqlite3_snapshot_get() must be matched by a call
+** The constructor for this object is [sqlite3_snapshot_get()].  The
-** to sqlite3_snapshot_free() to delete the snapshot handle. Not doing so
+** [sqlite3_snapshot_open()] method causes a fresh read transaction to refer
-** is a memory leak. The results of using a snapshot handle after it has 
+** to an historical snapshot (if possible).  The destructor for 
-** been deleted by sqlite3_snapshot_free() are undefined.
+** sqlite3_snapshot objects is [sqlite3_snapshot_free()].
-**
-** 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);
+
-void sqlite3_snapshot_free(sqlite3_snapshot*);
+/*
-int sqlite3_snapshot_open(sqlite3*, const char*, sqlite3_snapshot*);
+** CAPI3REF: Record A Database Snapshot
+** EXPERIMENTAL
+**
+** ^The [sqlite3_snapshot_get(D,S,P)] interface attempts to make a
+** new [sqlite3_snapshot] object that records the current state of
+** schema S in database connection D.  ^On success, the
+** [sqlite3_snapshot_get(D,S,P)] interface writes a pointer to the newly
+** created [sqlite3_snapshot] object into *P and returns SQLITE_OK.
+** ^If schema S of [database connection] D is not a [WAL mode] database
+** that is in a read transaction, then [sqlite3_snapshot_get(D,S,P)]
+** leaves the *P value unchanged and returns an appropriate [error code].
+**
+** The [sqlite3_snapshot] object returned from a successful call to
+** [sqlite3_snapshot_get()] must be freed using [sqlite3_snapshot_free()]
+** to avoid a memory leak.
+*/
+SQLITE_EXPERIMENTAL int sqlite3_snapshot_get(sqlite3*,const char*,sqlite3_snapshot **ppSnapshot);
+
+/*
+** CAPI3REF: Start a read transaction on an historical snapshot
+** EXPERIMENTAL
+**
+** ^The [sqlite3_snapshot_open(D,S,P)] interface attempts to move the
+** read transaction that is currently open on schema S of
+** [database connection] D so that it refers to historical [snapshot] P.
+** ^The [sqlite3_snapshot_open()] interface returns SQLITE_OK on success
+** or an appropriate [error code] if it fails.
+**
+** ^In order to succeed, a call to [sqlite3_snapshot_open(D,S,P)] must be
+** the first operation, apart from other sqlite3_snapshot_open() calls,
+** following the [BEGIN] that starts a new read transaction.
+** ^A [snapshot] will fail to open if it has been overwritten by a 
+** [checkpoint].  
+*/
+SQLITE_EXPERIMENTAL int sqlite3_snapshot_open(sqlite3*,const char*,sqlite3_snapshot*);
+
+/*
+** CAPI3REF: Destroy a snapshot
+** EXPERIMENTAL
+**
+** ^The [sqlite3_snapshot_free(P)] interface destroys [sqlite3_snapshot] P.
+** The application must eventually free every [sqlite3_snapshot] object
+** using this routine to avoid a memory leak.
+*/
+SQLITE_EXPERIMENTAL void sqlite3_snapshot_free(sqlite3_snapshot*);
 
 /*
 ** Undo the hack that converts floating point types to integer for

src/wal.c

@@ -3269,6 +3269,10 @@ int sqlite3WalHeapMemory(Wal *pWal){
 }
 
 #ifdef SQLITE_ENABLE_SNAPSHOT
+/* Create a snapshot object.  The content of a snapshot is opaque to
+** every other subsystem, so the WAL module can put whatever it needs
+** in the object.
+*/
 int sqlite3WalSnapshotGet(Wal *pWal, sqlite3_snapshot **ppSnapshot){
   int rc = SQLITE_OK;
   WalIndexHdr *pRet;
@@ -3286,6 +3290,8 @@ int sqlite3WalSnapshotGet(Wal *pWal, sqlite3_snapshot **ppSnapshot){
   return rc;
 }
 
+/* Try to open on pSnapshot when the next read-transaction starts
+*/
 void sqlite3WalSnapshotOpen(Wal *pWal, sqlite3_snapshot *pSnapshot){
   pWal->pSnapshot = (WalIndexHdr*)pSnapshot;
 }