From 9214c1efe831ca60df04f0a06bb6b1cfd5ca6d38 Mon Sep 17 00:00:00 2001
From: drh <drh@noemail.net>
Date: Wed, 8 Nov 2017 19:26:27 +0000
Subject: [PATCH] Extra comments on the sqlite3OsShmMap() call in
 walBeginUnlocked().  No changes to code.

FossilOrigin-Name: 033ee92bf4d5dc57f5cb8fd02d1154ae06f2d3261d214e7191a82c70c8ffebf7
---
 manifest      | 12 ++++++------
 manifest.uuid |  2 +-
 src/wal.c     | 10 +++++++++-
 3 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/manifest b/manifest
index 3f6afa398d..a22cee602e 100644
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Turns\sout\sthat\sSQLITE_READONLY_CANTLOCK\sis\san\shistorical\sname\sthat\smust\nbe\spreserved.\s\sSo\smake\sa\snew\sSQLITE_READLOCK_CANTINIT\sname\sinstead.
-D 2017-11-08T17:51:10.682
+C Extra\scomments\son\sthe\ssqlite3OsShmMap()\scall\sin\swalBeginUnlocked().\s\sNo\nchanges\sto\scode.
+D 2017-11-08T19:26:27.278
 F Makefile.in 5bae3f2f3d42f2ad52b141562d74872c97ac0fca6c54953c91bb150a0e6427a8
 F Makefile.linux-gcc 7bc79876b875010e8c8f9502eb935ca92aa3c434
 F Makefile.msc 3a5cb477ec3ce5274663b693164e349db63348667cd45bad78cc13d580b691e2
@@ -543,7 +543,7 @@ F src/vdbesort.c 731a09e5cb9e96b70c394c1b7cf3860fbe84acca7682e178615eb941a3a0ef2
 F src/vdbetrace.c 48e11ebe040c6b41d146abed2602e3d00d621d7ebe4eb29b0a0f1617fd3c2f6c
 F src/vtab.c 0e4885495172e1bdf54b12cce23b395ac74ef5729031f15e1bc1e3e6b360ed1a
 F src/vxworks.h d2988f4e5a61a4dfe82c6524dd3d6e4f2ce3cdb9
-F src/wal.c b1fef64a242ab30b5fdeeaba49150b420608681673b08833acd17024a179cb1e
+F src/wal.c 6903d391b6c224e45910795d66f97151428662c5f459d3b69997209dbcadc6f5
 F src/wal.h 8de5d2d3de0956d6f6cb48c83a4012d5f227b8fe940f3a349a4b7e85ebcb492a
 F src/walker.c d591e8a9ccf60abb010966b354fcea4aa08eba4d83675c2b281a8764c76cc22f
 F src/where.c b7a075f5fb3d912a891dcc3257f538372bb4a1622dd8ca7d752ad95ce8949ba4
@@ -1669,7 +1669,7 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
 F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
 F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P 6d7f94faa7e6de62f82bc6cac019508a9c1ffd6fa1d14f52fa93e9c06afdd32f
-R 1af2a9a9afceb6f159be2ed742a0108b
+P 04974a8b5c0e6748216226006ca9125529c8bb2a7a9df4641217eb1413426a14
+R eba2a72214a6da7d512bda6426cfe5de
 U drh
-Z 83682bfec24bdede404f3ec79bae717f
+Z 493ea33d970c37f0e10aaccf35cd6d47
diff --git a/manifest.uuid b/manifest.uuid
index 70823ee687..a866afde61 100644
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-04974a8b5c0e6748216226006ca9125529c8bb2a7a9df4641217eb1413426a14
\ No newline at end of file
+033ee92bf4d5dc57f5cb8fd02d1154ae06f2d3261d214e7191a82c70c8ffebf7
\ No newline at end of file
diff --git a/src/wal.c b/src/wal.c
index 11cdeb8440..afd0e3f7b6 100644
--- a/src/wal.c
+++ b/src/wal.c
@@ -2210,6 +2210,14 @@ static int walBeginUnlocked(Wal *pWal, int *pChanged){
   /* Try to map the *-shm file again. If it succeeds this time, then 
   ** a non-readonly_shm connection has already connected to the database.
   ** In this case, start over with opening the transaction.
+  **
+  ** The *-shm file was opened read-only, so sqlite3OsShmMap() can never
+  ** return SQLITE_OK here, as that would imply that it had established
+  ** a read/write mapping.  A return of SQLITE_READONLY means success - that
+  ** a mapping has been established to a shared-memory segment that is actively
+  ** maintained by a writer.  SQLITE_READONLY_CANTINIT means that all
+  ** all connections to the -shm file are read-only and hence the content
+  ** of the -shm file might be out-of-date.
   ** 
   ** The WAL_READ_LOCK(0) lock held by this client prevents a checkpoint
   ** from taking place. But it does not prevent the wal from being wrapped
@@ -2219,8 +2227,8 @@ static int walBeginUnlocked(Wal *pWal, int *pChanged){
   ** the unlocked transaction, as the other client may overwrite wal 
   ** frames that this client is still using.  */
   rc = sqlite3OsShmMap(pWal->pDbFd, 0, WALINDEX_PGSZ, 0, &pDummy);
+  assert( rc!=SQLITE_OK ); /* SQLITE_OK not possible for read-only connection */
   if( rc!=SQLITE_READONLY_CANTINIT ){
-    assert( rc!=SQLITE_OK );
     rc = (rc==SQLITE_READONLY ? WAL_RETRY : rc);
     goto begin_unlocked_out;
   }