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

wal.h.

FossilOrigin-Name: bbc385111b19071e20fe963fab814262c815b3e9

1 files changed, 25 insertions, 5 deletions

diff --git a/src/wal.h b/src/wal.h
index 64067ce09..f04344c63 100644
--- a/src/wal.h
+++ b/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_ */