-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.
-D 2015-12-10T20:03:08.672
+C Snapshot\sdocumentation\supdates.\s\sComment\schanges\sonly\s-\sno\schanges\sto\scode.
+D 2015-12-10T22:48:22.684
F Makefile.in 28bcd6149e050dff35d4dcfd97e890cd387a499d
F Makefile.linux-gcc 7bc79876b875010e8c8f9502eb935ca92aa3c434
F Makefile.msc e8fdca1cb89a1b58b5f4d3a130ea9a3d28cb314d
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
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
F tool/warnings-clang.sh f6aa929dc20ef1f856af04a730772f59283631d4
F tool/warnings.sh 48bd54594752d5be3337f12c72f28d2080cb630b
F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f
-P f3b743623a4501833478c8a86c0922931955aeb6
-R 50bb5d50d586d96f69cac8095fa25e56
-U dan
-Z 07077a92d084d80e6cdd7a283dbdc283
+P b9c90f10297d8516a661449e8af898e682c930aa
+R 359f52ff04c40d68d5a15fc7ff658a21
+U drh
+Z f10084cbd288f6e41be166b6d28c4cd6
** 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*);
-SQLITE_EXPERIMENTAL void sqlite3_value_free(sqlite3_value*);
+sqlite3_value *sqlite3_value_dup(const sqlite3_value*);
+void sqlite3_value_free(sqlite3_value*);
/*
** CAPI3REF: Obtain Aggregate Function Context
/*
** 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
-** databases - "main", "temp" and any attached databases.
+** file (page 1 is always "in use"). ^The [sqlite3_db_cacheflush(D)]
+** interface flushes caches for all schemas - "main", "temp", and
+** any [attached] databases.
**
-** 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
+** ^If this function needs to obtain extra database locks before dirty pages
+** 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
-** returned by the sqlite3_errcode() and sqlite3_errmsg() functions.
+** ^This function does not set the database handle error code or message
+** returned by the [sqlite3_errcode()] and [sqlite3_errmsg()] functions.
*/
int sqlite3_db_cacheflush(sqlite3*);
/*
-** CAPI3REF: Open old database snapshots.
-**
-** The second argument passed to sqlite3_snapshot_get() must be the name
-** of a database file attached to the database handle passed as the first.
-** 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
-** snapshot handle that may be used with sqlite3_snapshot_open() and returns
-** 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.
+** CAPI3REF: Database Snapshot
+** KEYWORDS: {snapshot}
+** EXPERIMENTAL
+**
+** An instance of the snapshot object records the state of a [WAL mode]
+** database for some specific point in history.
+**
+** In [WAL mode], multiple [database connections] that are open on the
+** same database file can each be reading a different historical version
+** 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.
+**
+** The sqlite3_snapshot object records state information about an historical
+** version of the database file so that it is possible to later open a new read
+** transaction that sees that historical version of the database rather than
+** the most recent version.
+**
+** The constructor for this object is [sqlite3_snapshot_get()]. The
+** [sqlite3_snapshot_open()] method causes a fresh read transaction to refer
+** to an historical snapshot (if possible). The destructor for
+** sqlite3_snapshot objects is [sqlite3_snapshot_free()].
*/
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
projects / thirdparty / sqlite.git / commitdiff
