From: drh Date: Thu, 10 Dec 2015 22:48:22 +0000 (+0000) Subject: Snapshot documentation updates. Comment changes only - no changes to code. X-Git-Tag: version-3.10.0~44^2~4 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=e230a8994e1b0f4d76482e5c04954859e2cd32da;p=thirdparty%2Fsqlite.git Snapshot documentation updates. Comment changes only - no changes to code. FossilOrigin-Name: ef51a398a04963508389ffe2f9d8359c1ec48261 --- diff --git a/manifest b/manifest index 8387bc5312..1988a1e007 100644 --- a/manifest +++ b/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. -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 @@ -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 -R 50bb5d50d586d96f69cac8095fa25e56 -U dan -Z 07077a92d084d80e6cdd7a283dbdc283 +P b9c90f10297d8516a661449e8af898e682c930aa +R 359f52ff04c40d68d5a15fc7ff658a21 +U drh +Z f10084cbd288f6e41be166b6d28c4cd6 diff --git a/manifest.uuid b/manifest.uuid index 3dacbbd066..d0158534a5 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -b9c90f10297d8516a661449e8af898e682c930aa \ No newline at end of file +ef51a398a04963508389ffe2f9d8359c1ec48261 \ No newline at end of file diff --git a/src/sqlite.h.in b/src/sqlite.h.in index 8dcf99eb2a..780a702307 100644 --- a/src/sqlite.h.in +++ b/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*); -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 @@ -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 -** 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 diff --git a/src/wal.c b/src/wal.c index e5527029ac..bfc5050908 100644 --- a/src/wal.c +++ b/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; }