From: drh Date: Fri, 18 Jul 2014 19:06:39 +0000 (+0000) Subject: Improved documentation for checkpoints and the busy handler. No changes X-Git-Tag: version-3.8.6~82 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=a6f5972c7529bc4b7f4c754278e2b5383126b6d0;p=thirdparty%2Fsqlite.git Improved documentation for checkpoints and the busy handler. No changes to code. FossilOrigin-Name: ca92c0240681b199c4b8ecc557792b8aea71692d --- diff --git a/manifest b/manifest index f047a472d0..1ef6e6429f 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C SQLite\shas\slong\saccepted\ssome\sunadvertised\sand\snon-standard\sjoin\ssyntax.\nAdd\sa\stest\sto\sensure\sthat\sfuture\sversions\scontinue\sto\saccept\sthis\snon-standard\nsyntax,\sto\savoid\sbreaking\slegacy\sapplications\sthat\suse\sthe\sundefined\ssyntax. -D 2014-07-18T17:39:48.053 +C Improved\sdocumentation\sfor\scheckpoints\sand\sthe\sbusy\shandler.\s\sNo\schanges\nto\scode. +D 2014-07-18T19:06:39.261 F Makefile.arm-wince-mingw32ce-gcc d6df77f1f48d690bd73162294bbba7f59507c72f F Makefile.in 1732320ecac3fee229d560d7ef2afa34681d1815 F Makefile.linux-gcc 91d710bdc4998cb015f39edf3cb314ec4f4d7e23 @@ -224,7 +224,7 @@ F src/resolve.c 5fc110baeacf120a73fe34e103f052632ff11a02 F src/rowset.c a9c9aae3234b44a6d7c6f5a3cadf90dce1e627be F src/select.c 6762c62e11b504aa014edceab8886495165e3a77 F src/shell.c 566aee8213372a2e81ba0eb34e9759f7b2574009 -F src/sqlite.h.in a98eb3e8c86c934ea6f5bcfc6b69653dde2f4ed4 +F src/sqlite.h.in fd8e3a36b0aded082dc93a4b89c1e85324b4cf75 F src/sqlite3.rc 11094cc6a157a028b301a9f06b3d03089ea37c3e F src/sqlite3ext.h 886f5a34de171002ad46fae8c36a7d8051c190fc F src/sqliteInt.h e88614d7371b80ff69dbbb5e4b9813ee93dfd890 @@ -1182,7 +1182,7 @@ F tool/vdbe_profile.tcl 67746953071a9f8f2f668b73fe899074e2c6d8c1 F tool/warnings-clang.sh f6aa929dc20ef1f856af04a730772f59283631d4 F tool/warnings.sh 0abfd78ceb09b7f7c27c688c8e3fe93268a13b32 F tool/win/sqlite.vsix deb315d026cc8400325c5863eef847784a219a2f -P fa80c64caa573297bf43cb5b11d9e7db58567200 -R 98a05e82af602a262cecfbef5a77de2c +P 824dde7fc48dbca6d6c956c4eb79bbfa2d139ee5 +R e12aaadd86bb0f0252aac83b76e58ccc U drh -Z 99ce618698b83450b2fdb30e802ca3fb +Z 06586dc6d29c2abfb50a449af797bf0e diff --git a/manifest.uuid b/manifest.uuid index e1252a9375..38385b2f75 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -824dde7fc48dbca6d6c956c4eb79bbfa2d139ee5 \ No newline at end of file +ca92c0240681b199c4b8ecc557792b8aea71692d \ No newline at end of file diff --git a/src/sqlite.h.in b/src/sqlite.h.in index 21ab67a4c2..93cde78340 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -2032,9 +2032,13 @@ int sqlite3_complete16(const void *sql); /* ** CAPI3REF: Register A Callback To Handle SQLITE_BUSY Errors ** -** ^This routine sets a callback function that might be invoked whenever -** an attempt is made to open a database table that another thread -** or process has locked. +** ^The sqlite3_busy_handler(D,X,P) routine sets a callback function X +** that might be invoked with argument P whenever +** an attempt is made to access a database table associated with +** [database connection] D when another thread +** or process has the table locked. +** The sqlite3_busy_handler() interface is used to implement +** [sqlite3_busy_timeout()] and [PRAGMA busy_timeout]. ** ** ^If the busy callback is NULL, then [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] ** is returned immediately upon encountering the lock. ^If the busy callback @@ -2043,16 +2047,18 @@ int sqlite3_complete16(const void *sql); ** ^The first argument to the busy handler is a copy of the void* pointer which ** is the third argument to sqlite3_busy_handler(). ^The second argument to ** the busy handler callback is the number of times that the busy handler has -** been invoked for this locking event. ^If the +** been invoked for the same locking event. ^If the ** busy callback returns 0, then no additional attempts are made to -** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned. +** access the database and [SQLITE_BUSY] or [SQLITE_IOERR_BLOCKED] is returned +** to the application. ** ^If the callback returns non-zero, then another attempt -** is made to open the database for reading and the cycle repeats. +** is made to access the database and the cycle repeats. ** ** The presence of a busy handler does not guarantee that it will be invoked ** when there is lock contention. ^If SQLite determines that invoking the busy ** handler could result in a deadlock, it will go ahead and return [SQLITE_BUSY] -** or [SQLITE_IOERR_BLOCKED] instead of invoking the busy handler. +** or [SQLITE_IOERR_BLOCKED] to the application instead of invoking the +** busy handler. ** Consider a scenario where one process is holding a read lock that ** it is trying to promote to a reserved lock and ** a second process is holding a reserved lock that it is trying @@ -2084,10 +2090,12 @@ int sqlite3_complete16(const void *sql); ** ^(There can only be a single busy handler defined for each ** [database connection]. Setting a new busy handler clears any ** previously set handler.)^ ^Note that calling [sqlite3_busy_timeout()] -** will also set or clear the busy handler. +** or evaluating [PRAGMA busy_timeout=N] will change the +** busy handler and thus clear any previously set busy handler. ** ** The busy callback should not take any actions which modify the -** database connection that invoked the busy handler. Any such actions +** database connection that invoked the busy handler. In other words, +** the busy handler is not reentrant. Any such actions ** result in undefined behavior. ** ** A busy handler must not close the database connection @@ -2112,6 +2120,8 @@ int sqlite3_busy_handler(sqlite3*, int(*)(void*,int), void*); ** [database connection] any any given moment. If another busy handler ** was defined (using [sqlite3_busy_handler()]) prior to calling ** this routine, that other busy handler is cleared.)^ +** +** See also: [PRAGMA busy_timeout] */ int sqlite3_busy_timeout(sqlite3*, int ms); @@ -7139,6 +7149,9 @@ void *sqlite3_wal_hook( ** ^The [wal_autocheckpoint pragma] can be used to invoke this interface ** from SQL. ** +** ^Checkpoints initiated by this mechanism are +** [sqlite3_wal_checkpoint_v2|PASSIVE]. +** ** ^Every new [database connection] defaults to having the auto-checkpoint ** enabled with a threshold of 1000 or [SQLITE_DEFAULT_WAL_AUTOCHECKPOINT] ** pages. The use of this interface @@ -7155,6 +7168,10 @@ int sqlite3_wal_autocheckpoint(sqlite3 *db, int N); ** empty string, then a checkpoint is run on all databases of ** connection D. ^If the database connection D is not in ** [WAL | write-ahead log mode] then this interface is a harmless no-op. +** ^The [sqlite3_wal_checkpoint(D,X)] interface initiates a +** [sqlite3_wal_checkpoint_v2|PASSIVE] checkpoint. +** Use the [sqlite3_wal_checkpoint_v2()] interface to get a FULL +** or RESET checkpoint. ** ** ^The [wal_checkpoint pragma] can be used to invoke this interface ** from SQL. ^The [sqlite3_wal_autocheckpoint()] interface and the @@ -7177,10 +7194,12 @@ int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb); ** Checkpoint as many frames as possible without waiting for any database ** readers or writers to finish. Sync the db file if all frames in the log ** are checkpointed. This mode is the same as calling -** sqlite3_wal_checkpoint(). The busy-handler callback is never invoked. +** sqlite3_wal_checkpoint(). The [sqlite3_busy_handler|busy-handler callback] +** is never invoked. ** **
SQLITE_CHECKPOINT_FULL
-** This mode blocks (calls the busy-handler callback) until there is no +** This mode blocks (it invokes the +** [sqlite3_busy_handler|busy-handler callback]) until there is no ** database writer and all readers are reading from the most recent database ** snapshot. It then checkpoints all frames in the log file and syncs the ** database file. This call blocks database writers while it is running, @@ -7188,7 +7207,8 @@ int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb); ** **
SQLITE_CHECKPOINT_RESTART
** This mode works the same way as SQLITE_CHECKPOINT_FULL, except after -** checkpointing the log file it blocks (calls the busy-handler callback) +** checkpointing the log file it blocks (calls the +** [sqlite3_busy_handler|busy-handler callback]) ** until all readers are reading from the database file only. This ensures ** that the next client to write to the database file restarts the log file ** from the beginning. This call blocks database writers while it is running,