Rename the sqlite3_log_hook() to sqlite3_wal_hook(). Added comments to

wal.h.

FossilOrigin-Name: bbc385111b19071e20fe963fab814262c815b3e9

manifest

@@ -1,5 +1,8 @@
-C Merge\stwo\s"wal"\sleaves.
+-----BEGIN PGP SIGNED MESSAGE-----
-D 2010-04-27T18:49:54
+Hash: SHA1
+
+C Rename\sthe\ssqlite3_log_hook()\sto\ssqlite3_wal_hook().\s\sAdded\scomments\sto\nwal.h.
+D 2010-04-28T14:42:19
 F Makefile.arm-wince-mingw32ce-gcc fcd5e9cd67fe88836360bb4f9ef4cb7f8e2fb5a0
 F Makefile.in d83a0ffef3dcbfb08b410a6c6dd6c009ec9167fb
 F Makefile.linux-gcc d53183f4aa6a9192d249731c90dbdffbd2c68654
@@ -131,7 +134,7 @@ F src/journal.c b0ea6b70b532961118ab70301c00a33089f9315c
 F src/legacy.c a199d7683d60cef73089e892409113e69c23a99f
 F src/lempar.c 7f026423f4d71d989e719a743f98a1cbd4e6d99e
 F src/loadext.c 1c7a61ce1281041f437333f366a96aa0d29bb581
-F src/main.c 867de6aa444abd97771b2b70472f448d65c1c77e
+F src/main.c 569561a238a0bb6d55affbaa224ddc885c91df2b
 F src/malloc.c a08f16d134f0bfab6b20c3cd142ebf3e58235a6a
 F src/mem0.c 6a55ebe57c46ca1a7d98da93aaa07f99f1059645
 F src/mem1.c 89d4ea8d5cdd55635cbaa48ad53132af6294cbb2
@@ -166,13 +169,13 @@ F src/resolve.c ac5f1a713cd1ae77f08b83cc69581e11bf5ae6f9
 F src/rowset.c 69afa95a97c524ba6faf3805e717b5b7ae85a697
 F src/select.c c03d8a0565febcde8c6a12c5d77d065fddae889b
 F src/shell.c c40427c7245535a04a9cb4a417b6cc05c022e6a4
-F src/sqlite.h.in f9399ee58862fd146eff9725dda83b5c82d04a93
+F src/sqlite.h.in 9529106a7608b57bbe9e290cdddb203bd383f888
 F src/sqlite3ext.h 69dfb8116af51b84a029cddb3b35062354270c89
 F src/sqliteInt.h 700a2df7b8dfe57c3b8d83c52ff40928e026220c
 F src/sqliteLimit.h 3afab2291762b5d09ae20c18feb8e9fa935a60a6
 F src/status.c 4df6fe7dce2d256130b905847c6c60055882bdbe
 F src/table.c 2cd62736f845d82200acfa1287e33feb3c15d62e
-F src/tclsqlite.c e27e0457109d72c7404df08af1726ff6ddc3d92c
+F src/tclsqlite.c 4de81521174fedacd8393ea7b70b730ce17f8eae
 F src/test1.c 64b5b8135080b94370e8100e5066bb394f5c3122
 F src/test2.c b6b43413d495addd039a88b87d65c839f86b18cb
 F src/test3.c 4c21700c73a890a47fc685c1097bfb661346ac94
@@ -222,7 +225,7 @@ F src/vdbemem.c 2a82f455f6ca6f78b59fb312f96054c04ae0ead1
 F src/vdbetrace.c 864cef96919323482ebd9986f2132435115e9cc2
 F src/vtab.c a0f8a40274e4261696ef57aa806de2776ab72cda
 F src/wal.c 1576b36d55220d42598a5fb48a06e083efecea75
-F src/wal.h 812101dd76610401fbcd44114e7e8b7ce0224645
+F src/wal.h c60781e78e394af07ece3b64a11192eb442241c1
 F src/walker.c 3112bb3afe1d85dc52317cb1d752055e9a781f8f
 F src/where.c faadd9c2bf08868e5135192b44e0d753e363a885
 F test/aggerror.test a867e273ef9e3d7919f03ef4f0e8c0d2767944f2
@@ -599,7 +602,7 @@ F test/substr.test 18f57c4ca8a598805c4d64e304c418734d843c1a
 F test/sync.test ded6b39d8d8ca3c0c5518516c6371b3316d3e3a3
 F test/table.test bf102a5669c4db7a41330802f24a4a81a4204f83
 F test/tableapi.test 7262a8cbaa9965d429f1cbd2747edc185fa56516
-F test/tclsqlite.test 7378a4e7474d9ffdb7c930086112b829e5955fb0
+F test/tclsqlite.test 013133fa83128569c6fb8a7a48dc7c4507e6ff1c
 F test/tempdb.test 1bf52da28a9c24e29717362a87722dff08feb72b
 F test/temptable.test f42121a0d29a62f00f93274464164177ab1cc24a
 F test/temptrigger.test b0273db072ce5f37cf19140ceb1f0d524bbe9f05
@@ -761,7 +764,7 @@ F test/vtab_shared.test 0eff9ce4f19facbe0a3e693f6c14b80711a4222d
 F test/wal.test bc99b1656b721fddd2dfeea0b0e77b147e40e6da
 F test/walbak.test f6fde9a5f59d0c697cb1f4af7876178c2f69a7ba
 F test/walcrash.test f022cee7eb7baa5fb898726120a6a4073dd831d1
-F test/walhook.test 76a559e262f0715c470bade4a8d8333035f8ee47
+F test/walhook.test 287a69d662939604f2e0452dace2cec8ef634d5e
 F test/walmode.test 40119078da084e6a7403ba57485d5a86ee0e2646
 F test/walslow.test 38076d5fad49e3678027be0f8110e6a32d531dc2
 F test/walthread.test a7962d8b899366cc71f8381d9aeab8ae9e1b544d
@@ -808,7 +811,14 @@ F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff
 F tool/speedtest8.c 2902c46588c40b55661e471d7a86e4dd71a18224
 F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e
 F tool/vdbe-compress.tcl d70ea6d8a19e3571d7ab8c9b75cba86d1173ff0f
-P be44349d2b790fb470fcc9fb6a12e8b1076dc645 ed715b47c5f7657fbf901805981867898054b14d
+P 8c2d43babd61fe2225d5c402174253f412604092
-R 543123f4859d04253152521c95f2472b
+R d2467063cf37b05312bd03bb938b0ac5
-U dan
+U drh
-Z 67c1d58e24d1fcb9816b2a39774cf9f7
+Z 7c95869a158e03c8e63f0877555a0133
+-----BEGIN PGP SIGNATURE-----
+Version: GnuPG v1.4.6 (GNU/Linux)
+
+iD8DBQFL2ElOoxKgR168RlERAmaCAJ0cROgoBzwR39dDYWGzjUDfWHeq+ACfdKsQ
+SQEr/7S7IaJ1k5L/fD6AU0g=
+=eywR
+-----END PGP SIGNATURE-----

manifest.uuid

@@ -1 +1 @@
-8c2d43babd61fe2225d5c402174253f412604092
+bbc385111b19071e20fe963fab814262c815b3e9

src/main.c

@@ -1190,7 +1190,7 @@ void *sqlite3_rollback_hook(
 ** Register a callback to be invoked each time a transaction is written
 ** into the write-ahead-log by this database connection.
 */
-void *sqlite3_log_hook(
+void *sqlite3_wal_hook(
   sqlite3 *db,                    /* Attach the hook to this db handle */
   int(*xCallback)(void *, sqlite3*, const char*, int),
   void *pArg                      /* First argument passed to xCallback() */

src/sqlite.h.in

@@ -5761,9 +5761,9 @@ int sqlite3_strnicmp(const char *, const char *, int);
 void sqlite3_log(int iErrCode, const char *zFormat, ...);
 
 /*
-** Experimental WAL callback interface.
+** CAPI3REF: Write-Ahead Log Commit Hook
 **
-** The [sqlite3_log_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). 
@@ -5773,7 +5773,7 @@ void sqlite3_log(int iErrCode, const char *zFormat, ...);
 ** may read, write or checkpoint the database as required.
 **
 ** The first parameter passed to the callback function when it is invoked
-** is a copy of the third parameter passed to sqlite3_log_hook() when
+** 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
@@ -5785,10 +5785,10 @@ void sqlite3_log(int iErrCode, const char *zFormat, ...);
 ** no special action is taken.
 **
 ** A single database handle may have at most a single log callback 
-** registered at one time. Calling [sqlite3_log_hook()] replaces any
+** registered at one time. Calling [sqlite3_wal_hook()] replaces any
 ** previously registered log callback. 
 */
-void *sqlite3_log_hook(
+void *sqlite3_wal_hook(
   sqlite3*, 
   int(*)(void *,sqlite3*,const char*,int),
   void*

src/tclsqlite.c

@@ -1570,12 +1570,12 @@ static int DbObjCmd(void *cd, Tcl_Interp *interp, int objc,Tcl_Obj *const*objv){
     "complete",           "copy",              "enable_load_extension",
     "errorcode",          "eval",              "exists",
     "function",           "incrblob",          "interrupt",
-    "last_insert_rowid",  "log_hook",          "nullvalue",
+    "last_insert_rowid",  "nullvalue",         "onecolumn",
-    "onecolumn",          "profile",           "progress",
+    "profile",            "progress",          "rekey",
-    "rekey",              "restore",           "rollback_hook",     
+    "restore",            "rollback_hook",     "status",
-    "status",             "timeout",           "total_changes",     
+    "timeout",            "total_changes",     "trace",
-    "trace",              "transaction",       "unlock_notify",     
+    "transaction",        "unlock_notify",     "update_hook",
-    "update_hook",        "version",            0                    
+    "version",            "wal_hook",          0
   };
   enum DB_enum {
     DB_AUTHORIZER,        DB_BACKUP,           DB_BUSY,
@@ -1584,12 +1584,12 @@ static int DbObjCmd(void *cd, Tcl_Interp *interp, int objc,Tcl_Obj *const*objv){
     DB_COMPLETE,          DB_COPY,             DB_ENABLE_LOAD_EXTENSION,
     DB_ERRORCODE,         DB_EVAL,             DB_EXISTS,
     DB_FUNCTION,          DB_INCRBLOB,         DB_INTERRUPT,
-    DB_LAST_INSERT_ROWID, DB_LOG_HOOK,         DB_NULLVALUE,
+    DB_LAST_INSERT_ROWID, DB_NULLVALUE,        DB_ONECOLUMN,
-    DB_ONECOLUMN,         DB_PROFILE,          DB_PROGRESS,
+    DB_PROFILE,           DB_PROGRESS,         DB_REKEY,
-    DB_REKEY,             DB_RESTORE,          DB_ROLLBACK_HOOK,    
+    DB_RESTORE,           DB_ROLLBACK_HOOK,    DB_STATUS,
-    DB_STATUS,            DB_TIMEOUT,          DB_TOTAL_CHANGES,    
+    DB_TIMEOUT,           DB_TOTAL_CHANGES,    DB_TRACE,
-    DB_TRACE,             DB_TRANSACTION,      DB_UNLOCK_NOTIFY,    
+    DB_TRANSACTION,       DB_UNLOCK_NOTIFY,    DB_UPDATE_HOOK,
-    DB_UPDATE_HOOK,       DB_VERSION
+    DB_VERSION,           DB_WAL_HOOK
   };
   /* don't leave trailing commas on DB_enum, it confuses the AIX xlc compiler */
 
@@ -2760,11 +2760,11 @@ static int DbObjCmd(void *cd, Tcl_Interp *interp, int objc,Tcl_Obj *const*objv){
   }
 
   /*
-  **    $db log_hook ?script?
+  **    $db wal_hook ?script?
   **    $db update_hook ?script?
   **    $db rollback_hook ?script?
   */
-  case DB_LOG_HOOK: 
+  case DB_WAL_HOOK: 
   case DB_UPDATE_HOOK: 
   case DB_ROLLBACK_HOOK: {
 
@@ -2774,7 +2774,7 @@ static int DbObjCmd(void *cd, Tcl_Interp *interp, int objc,Tcl_Obj *const*objv){
     Tcl_Obj **ppHook; 
     if( choice==DB_UPDATE_HOOK ){
       ppHook = &pDb->pUpdateHook;
-    }else if( choice==DB_LOG_HOOK ){
+    }else if( choice==DB_WAL_HOOK ){
       ppHook = &pDb->pLogHook;
     }else{
       ppHook = &pDb->pRollbackHook;
@@ -2801,7 +2801,7 @@ static int DbObjCmd(void *cd, Tcl_Interp *interp, int objc,Tcl_Obj *const*objv){
 
     sqlite3_update_hook(pDb->db, (pDb->pUpdateHook?DbUpdateHandler:0), pDb);
     sqlite3_rollback_hook(pDb->db,(pDb->pRollbackHook?DbRollbackHandler:0),pDb);
-    sqlite3_log_hook(pDb->db,(pDb->pLogHook?DbLogHandler:0),pDb);
+    sqlite3_wal_hook(pDb->db,(pDb->pLogHook?DbLogHandler:0),pDb);
 
     break;
   }

src/wal.h

@@ -19,19 +19,30 @@
 
 #include "sqliteInt.h"
 
-/* Connection to a log file. There is one object of this type for each pager. */
+/* Connection to a write-ahead log (WAL) file. 
+** There is one object of this type for each pager. 
+*/
 typedef struct Log Log;
 
-/* Open and close a connection to a log file. */
+/* Open and close a connection to a write-ahead log. */
 int sqlite3WalOpen(sqlite3_vfs*, const char *zDb, Log **ppLog);
 int sqlite3WalClose(Log *pLog, sqlite3_file *pFd, int sync_flags, u8 *zBuf);
 
-/* Used by readers to open (lock) and close (unlock) a snapshot. */
+/* Used by readers to open (lock) and close (unlock) a snapshot.  A 
+** snapshot is like a read-transaction.  It is the state of the database
+** at an instant in time.  sqlite3WalOpenSnapshot gets a read lock and
+** preserves the current state even if the other threads or processes
+** write to or checkpoint the WAL.  sqlite3WalCloseSnapshot() closes the
+** transaction and releases the lock.
+*/
 int sqlite3WalOpenSnapshot(Log *pLog, int *);
 void sqlite3WalCloseSnapshot(Log *pLog);
 
-/* Read a page from the log, if it is present. */
+/* Read a page from the write-ahead log, if it is present. */
 int sqlite3WalRead(Log *pLog, Pgno pgno, int *pInLog, u8 *pOut);
+
+/* Return the size of the database as it existed at the beginning
+** of the snapshot */
 void sqlite3WalDbsize(Log *pLog, Pgno *pPgno);
 
 /* Obtain or release the WRITER lock. */
@@ -40,7 +51,12 @@ int sqlite3WalWriteLock(Log *pLog, int op);
 /* Undo any frames written (but not committed) to the log */
 int sqlite3WalUndo(Log *pLog, int (*xUndo)(void *, Pgno), void *pUndoCtx);
 
+/* Return an integer that records the current (uncommitted) write
+** position in the WAL */
 u32 sqlite3WalSavepoint(Log *pLog);
+
+/* Move the write position of the WAL back to iFrame.  Called in
+** response to a ROLLBACK TO command. */
 int sqlite3WalSavepointUndo(Log *pLog, u32 iFrame);
 
 /* Return true if data has been written but not committed to the log file. */
@@ -59,7 +75,11 @@ int sqlite3WalCheckpoint(
   void *pBusyHandlerArg           /* Argument to pass to xBusyHandler */
 );
 
-/* Return the value to pass to a log callback. Or 0 for no callback. */
+/* Return the value to pass to a sqlite3_wal_hook callback, the
+** number of frames in the WAL at the point of the last commit since
+** sqlite3WalCallback() was called.  If no commits have occurred since
+** the last call, then return 0.
+*/
 int sqlite3WalCallback(Log *pLog);
 
 #endif /* _WAL_H_ */

test/tclsqlite.test

@@ -35,7 +35,7 @@ do_test tcl-1.1 {
 do_test tcl-1.2 {
   set v [catch {db bogus} msg]
   lappend v $msg
-} {1 {bad option "bogus": must be authorizer, backup, busy, cache, changes, close, collate, collation_needed, commit_hook, complete, copy, enable_load_extension, errorcode, eval, exists, function, incrblob, interrupt, last_insert_rowid, log_hook, nullvalue, onecolumn, profile, progress, rekey, restore, rollback_hook, status, timeout, total_changes, trace, transaction, unlock_notify, update_hook, or version}}
+} {1 {bad option "bogus": must be authorizer, backup, busy, cache, changes, close, collate, collation_needed, commit_hook, complete, copy, enable_load_extension, errorcode, eval, exists, function, incrblob, interrupt, last_insert_rowid, nullvalue, onecolumn, profile, progress, rekey, restore, rollback_hook, status, timeout, total_changes, trace, transaction, unlock_notify, update_hook, version, or wal_hook}}
 do_test tcl-1.2.1 {
   set v [catch {db cache bogus} msg]
   lappend v $msg

test/walhook.test

@@ -25,31 +25,31 @@ proc sqlite3_wal {args} {
   }
 }
 sqlite3_wal db test.db
-db log_hook log_hook
+db wal_hook wal_hook
 
-set ::log_hook [list]
+set ::wal_hook [list]
-proc log_hook {zDb nEntry} {
+proc wal_hook {zDb nEntry} {
-  lappend ::log_hook $zDb $nEntry
+  lappend ::wal_hook $zDb $nEntry
   return 0
 }
 
 do_test walhook-1.1 {
   execsql { CREATE TABLE t1(i PRIMARY KEY, j) }
-  set ::log_hook
+  set ::wal_hook
 } {main 3}
 do_test walhook-1.2 {
-  set ::log_hook [list]
+  set ::wal_hook [list]
   execsql { INSERT INTO t1 VALUES(1, 'one') }
-  set ::log_hook
+  set ::wal_hook
 } {main 5}
 do_test walhook-1.3 {
-  proc log_hook {args} { return 1 }
+  proc wal_hook {args} { return 1 }
   execsql { INSERT INTO t1 VALUES(2, 'two') }
   file size test.db
 } [expr 3*1024]
 
 do_test walhook-1.4 {
-  proc log_hook {zDb nEntry} { 
+  proc wal_hook {zDb nEntry} { 
     execsql { PRAGMA checkpoint }
     return 0
   }
@@ -59,7 +59,7 @@ do_test walhook-1.4 {
 
 do_test walhook-1.5 {
   sqlite3_wal db2 test.db
-  proc log_hook {zDb nEntry} { 
+  proc wal_hook {zDb nEntry} { 
     execsql { PRAGMA checkpoint } db2
     return 0
   }
@@ -70,4 +70,3 @@ do_test walhook-1.5 {
 catch { db2 close }
 catch { db close }
 finish_test
-