Merge two "wal"

leaves.

FossilOrigin-Name: 13d2d5a66e9eaa81aa6314354201ee1fbd2b3824

5 files changed, 65 insertions, 58 deletions

diff --git a/src/main.c b/src/main.c
index 80c15963a..3e7c1257c 100644
--- a/src/main.c
+++ b/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() */
diff --git a/src/os_unix.c b/src/os_unix.c
index d603caa0d..7e3930a1e 100644
--- a/src/os_unix.c
+++ b/src/os_unix.c
@@ -4697,26 +4697,11 @@ static int unixShmRelease(sqlite3_shm *pSharedMem){
 */
 static int unixShmLock(
   sqlite3_shm *pSharedMem,   /* Pointer from unixShmOpen() */
-  int lockType,              /* _RDLK, _WRLK, or _UNLK, possibly ORed _BLOCK */
-  int ofst,                  /* Start of lock region */
-  int nByte                  /* Size of lock region in bytes */
+  int desiredLock,           /* The locking state desired */
+  int *pGotLock,             /* The locking state actually obtained */
+  int shouldBlock            /* Block for the lock if true and possible */
 ){
-  struct unixShm *p = (struct unixShm*)pSharedMem;
-  struct flock f;
-  int op;
-  int rc;
-  
-  f.l_whence = SEEK_SET;
-  f.l_start = ofst;
-  f.l_len = nByte;
-  switch( lockType & 0x07 ){
-    case SQLITE_SHM_RDLK:  f.l_type = F_RDLCK;   break;
-    case SQLITE_SHM_WRLK:  f.l_type = F_WRLCK;   break;
-    case SQLITE_SHM_UNLK:  f.l_type = F_UNLCK;   break;
-  }
-  op = (lockType & 0x08)!=0 ? F_SETLKW : F_SETLK;
-  rc = fcntl(p->fd.h, op, &f);
-  return (rc==0) ? SQLITE_OK : SQLITE_BUSY;
+  return SQLITE_OK;
 }
 
 /*
diff --git a/src/sqlite.h.in b/src/sqlite.h.in
index 7bc750944..9f6f1bc96 100644
--- a/src/sqlite.h.in
+++ b/src/sqlite.h.in
@@ -848,7 +848,7 @@ struct sqlite3_vfs {
   int (*xShmRelease)(sqlite3_shm*);
   int (*xShmPush)(sqlite3_shm*);
   int (*xShmPull)(sqlite3_shm*);
-  int (*xShmLock)(sqlite3_shm*, int lockType, int ofst, int nByte);
+  int (*xShmLock)(sqlite3_shm*, int desiredLock, int *gotLock, int shouldBlock);
   int (*xShmClose)(sqlite3_shm*);
   int (*xShmDelete)(sqlite3_vfs*, const char *zName);
   int (*xRename)(sqlite3_vfs*, const char *zOld, const char *zNew, int dirSync);
@@ -880,18 +880,20 @@ struct sqlite3_vfs {
 /*
 ** CAPI3REF: Flags for the xShmLock VFS method
 **
-** These integer constants can be used as the second parameter to
-** the xShmLock method of an [sqlite3_vfs] object.  They determine
-** the specific locking action.  Exactly one of the first three
-** values must be used ini the lockType parameter.  The fourth
-** value (SQLITE_SHM_BLOCK) can optionally be ORed into the lockType
-** parameter to cause the thread to block until the lock becomes
-** available.
+** These integer constants define the various locking states that
+** an sqlite3_shm object can be in.  The SQLITE_SHM_QUERY integer
+** is not a valid data - it is a constant pasted to the 
+** sqlite3_vfs.xShmLock() method for querying the current lock
+** state.
 */
-#define SQLITE_SHM_RDLK   0x01
-#define SQLITE_SHM_WRLK   0x02
-#define SQLITE_SHM_UNLK   0x04
-#define SQLITE_SHM_BLOCK  0x08
+#define SQLITE_SHM_UNLOCK       0
+#define SQLITE_SHM_READ_PREFIX  1
+#define SQLITE_SHM_READ_FULL    2
+#define SQLITE_SHM_WRITE        3
+#define SQLITE_SHM_PENDING      4
+#define SQLITE_SHM_CHECKPOINT   5
+#define SQLITE_SHM_RECOVER      6
+#define SQLITE_SHM_QUERY        (-1)
 
 /*
 ** CAPI3REF: Initialize The SQLite Library
@@ -5761,9 +5763,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 +5775,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 +5787,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*
diff --git a/src/tclsqlite.c b/src/tclsqlite.c
index 8582ce34e..4ef51d856 100644
--- a/src/tclsqlite.c
+++ b/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",
-    "onecolumn",          "profile",           "progress",
-    "rekey",              "restore",           "rollback_hook",     
-    "status",             "timeout",           "total_changes",     
-    "trace",              "transaction",       "unlock_notify",     
-    "update_hook",        "version",            0                    
+    "last_insert_rowid",  "nullvalue",         "onecolumn",
+    "profile",            "progress",          "rekey",
+    "restore",            "rollback_hook",     "status",
+    "timeout",            "total_changes",     "trace",
+    "transaction",        "unlock_notify",     "update_hook",
+    "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_ONECOLUMN,         DB_PROFILE,          DB_PROGRESS,
-    DB_REKEY,             DB_RESTORE,          DB_ROLLBACK_HOOK,    
-    DB_STATUS,            DB_TIMEOUT,          DB_TOTAL_CHANGES,    
-    DB_TRACE,             DB_TRANSACTION,      DB_UNLOCK_NOTIFY,    
-    DB_UPDATE_HOOK,       DB_VERSION
+    DB_LAST_INSERT_ROWID, DB_NULLVALUE,        DB_ONECOLUMN,
+    DB_PROFILE,           DB_PROGRESS,         DB_REKEY,
+    DB_RESTORE,           DB_ROLLBACK_HOOK,    DB_STATUS,
+    DB_TIMEOUT,           DB_TOTAL_CHANGES,    DB_TRACE,
+    DB_TRANSACTION,       DB_UNLOCK_NOTIFY,    DB_UPDATE_HOOK,
+    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;
   }
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_ */