From: drh Date: Fri, 7 May 2010 13:57:11 +0000 (+0000) Subject: Updates to documentation on the C interfaces supporting WAL. No functional X-Git-Tag: version-3.7.2~398 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=005e19c4c124e1921644faf53a7fbfa491370d94;p=thirdparty%2Fsqlite.git Updates to documentation on the C interfaces supporting WAL. No functional changes to code. FossilOrigin-Name: 681ba20cf077e9a0fccd51ed50101ad0f2c67eb3 --- diff --git a/manifest b/manifest index e805da27ae..8ac08f6b79 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,8 @@ -C Fix\sa\srecently\sintroduced\sproblem\sin\swal.test. -D 2010-05-07T13:52:42 +-----BEGIN PGP SIGNED MESSAGE----- +Hash: SHA1 + +C Updates\sto\sdocumentation\son\sthe\sC\sinterfaces\ssupporting\sWAL.\s\sNo\sfunctional\nchanges\sto\scode. +D 2010-05-07T13:57:12 F Makefile.arm-wince-mingw32ce-gcc fcd5e9cd67fe88836360bb4f9ef4cb7f8e2fb5a0 F Makefile.in a5cad1f8f3e021356bfcc6c77dc16f6f1952bbc3 F Makefile.linux-gcc d53183f4aa6a9192d249731c90dbdffbd2c68654 @@ -168,7 +171,7 @@ F src/resolve.c ac5f1a713cd1ae77f08b83cc69581e11bf5ae6f9 F src/rowset.c 69afa95a97c524ba6faf3805e717b5b7ae85a697 F src/select.c c03d8a0565febcde8c6a12c5d77d065fddae889b F src/shell.c fd4ccdb37c3b68de0623eb938a649e0990710714 -F src/sqlite.h.in c68d5a6c13c04812b2873bb93d2132d1f5d3ccf8 +F src/sqlite.h.in 72407bf49d35744cbfd13f6d51f1a03b15c5f263 F src/sqlite3ext.h 69dfb8116af51b84a029cddb3b35062354270c89 F src/sqliteInt.h 9819b45610abeca390176243a9a31758c1f0ac7a F src/sqliteLimit.h 196e2f83c3b444c4548fc1874f52f84fdbda40f3 @@ -813,7 +816,14 @@ F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff F tool/speedtest8.c 2902c46588c40b55661e471d7a86e4dd71a18224 F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e F tool/vdbe-compress.tcl d70ea6d8a19e3571d7ab8c9b75cba86d1173ff0f -P 4cde92909c20982f7d4e6b550f55d786df398ccd -R 20295599dce4718d671500354e44ba39 -U dan -Z b94275bafe790cd9e95d1bb57da8fef5 +P 79b52d0ff7a7b717bde55b97ff05ad17418bc7d7 +R cf887097965d8442a23107a6bcf8ae69 +U drh +Z 3287b7b783eafdd741af3505682fd853 +-----BEGIN PGP SIGNATURE----- +Version: GnuPG v1.4.6 (GNU/Linux) + +iD8DBQFL5Bw7oxKgR168RlERAnMgAJ97SOKasZYbinquvGNYLuxkfkXlhgCfSe8C +y1iASut6U+xw7S/tf+oygHc= +=Uyfx +-----END PGP SIGNATURE----- diff --git a/manifest.uuid b/manifest.uuid index baba768134..dbe115d5bb 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -79b52d0ff7a7b717bde55b97ff05ad17418bc7d7 \ No newline at end of file +681ba20cf077e9a0fccd51ed50101ad0f2c67eb3 \ No newline at end of file diff --git a/src/sqlite.h.in b/src/sqlite.h.in index e59b02c74b..f2b25c0ad6 100644 --- a/src/sqlite.h.in +++ b/src/sqlite.h.in @@ -5763,31 +5763,34 @@ void sqlite3_log(int iErrCode, const char *zFormat, ...); /* ** CAPI3REF: Write-Ahead Log Commit Hook ** -** The [sqlite3_wal_hook()] function is used to register a callback that +** ^The [sqlite3_wal_hook()] function is used to register a callback that ** will be invoked each time a database connection commits data to a -** write-ahead-log (i.e. whenever a transaction is committed in -** journal_mode=WAL mode). +** [write-ahead log] (i.e. whenever a transaction is committed in +** [journal_mode | journal_mode=WAL mode]). ** -** The callback is invoked by SQLite after the commit has taken place and +** ^The callback is invoked by SQLite after the commit has taken place and ** the associated write-lock on the database released, so the implementation -** may read, write or checkpoint the database as required. +** may read, write or [checkpoint] the database as required. ** -** The first parameter passed to the callback function when it is invoked +** ^The first parameter passed to the callback function when it is invoked ** is a copy of the third parameter passed to sqlite3_wal_hook() when -** registering the callback. The second is a copy of the database handle. -** The third parameter is the name of the database that was written to - -** either "main" or the name of an ATTACHed database. The fourth parameter -** is the number of pages currently in the log file, including those that -** were just committed. +** registering the callback. ^The second is a copy of the database handle. +** ^The third parameter is the name of the database that was written to - +** either "main" or the name of an ATTACHed database. ^The fourth parameter +** is the number of pages currently in the write-ahead log file, +** including those that were just committed. ** -** The callback function should normally return SQLITE_OK. If an error +** The callback function should normally return SQLITE_OK. ^If an error ** code is returned, that error will propagate back up through the ** SQLite code base to cause the statement that provoked the callback -** to fail. +** to report an error, though the commit will have still occurred. ** -** A single database handle may have at most a single log callback -** registered at one time. Calling [sqlite3_wal_hook()] replaces any -** previously registered log callback. +** A single database handle may have at most a single write-ahead log callback +** registered at one time. ^Calling [sqlite3_wal_hook()] replaces any +** previously registered write-ahead log callback. Note that the +** [sqlite3_wal_autocheckpoint()] interface and the +** [wal_autocheckpoint pragma] both invoke [sqlite3_wal_hook()] and will +** those overwrite any prior [sqlite3_wal_hook()] settings. */ void *sqlite3_wal_hook( sqlite3*, @@ -5798,28 +5801,42 @@ void *sqlite3_wal_hook( /* ** CAPI3REF: Configure an auto-checkpoint ** -** The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around +** ^The [sqlite3_wal_autocheckpoint(D,N)] is a wrapper around ** [sqlite3_wal_hook()] that causes any database on [database connection] D -** to automatically checkpoint +** to automatically [checkpoint] ** after committing a transaction if there are N or -** more frames in the write-ahead-log file. Passing zero or +** more frames in the [write-ahead log] file. ^Passing zero or ** a negative value as the nFrame parameter disables automatic ** checkpoints entirely. ** -** The callback registered by this function replaces any existing callback -** registered using [sqlite3_wal_hook()]. Likewise, registering a callback +** ^The callback registered by this function replaces any existing callback +** registered using [sqlite3_wal_hook()]. ^Likewise, registering a callback ** using [sqlite3_wal_hook()] disables the automatic checkpoint mechanism ** configured by this function. +** +** ^The [wal_autocheckpoint pragma] can be used to invoke this interface +** from SQL. +** +** ^Every new [database connection] defaults to having the auto-checkpoint +** enabled with a threshold of 1000 pages. The use of this interface +** is only necessary if the default setting is found to be suboptimal +** for a particular application. */ int sqlite3_wal_autocheckpoint(sqlite3 *db, int N); /* ** CAPI3REF: Checkpoint a database ** -** The [sqlite3_wal_checkpoint(D,X)] interface causes database named X -** on [database connection] D to be checkpointed. If X is NULL or an +** ^The [sqlite3_wal_checkpoint(D,X)] interface causes database named X +** on [database connection] D to be [checkpointed]. ^If X is NULL or an ** empty string, then a checkpoint is run on all databases of -** connection D. +** connection D. If the database connection D is not in +** [WAL | write-ahead log mode] then this interface is a harmless no-op. +** +** The [wal_checkpoint pragma] can be used to invoke this interface +** from SQL. The [sqlite3_wal_autocheckpoint()] interface and the +** [wal_autocheckpoint pragma] can be used to cause this interface to be +** run whenever the WAL reaches a certain size threshold. */ int sqlite3_wal_checkpoint(sqlite3 *db, const char *zDb);