Updates to documentation on the C interfaces supporting WAL. No functional

changes to code.

FossilOrigin-Name: 681ba20cf077e9a0fccd51ed50101ad0f2c67eb3

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-----

manifest.uuid

@@ -1 +1 @@
-79b52d0ff7a7b717bde55b97ff05ad17418bc7d7
+681ba20cf077e9a0fccd51ed50101ad0f2c67eb3

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);