From f42f25c2c5388a14c8775488c4767ed9acf6895d Mon Sep 17 00:00:00 2001
From: danielk1977 <danielk1977@noemail.net>
Date: Fri, 25 Jun 2004 07:21:28 +0000
Subject: [PATCH] Add a comment on the implementation of sqlite3OsLock(). No
 code changes. (CVS 1688)

FossilOrigin-Name: 084f3fffbdeb1e2b375817ae1111b867c9d32559
---
 manifest      | 14 +++++++-------
 manifest.uuid |  2 +-
 src/os_unix.c | 38 ++++++++++++++++++++++++++++++++++++++
 src/pager.c   |  4 ++--
 4 files changed, 48 insertions(+), 10 deletions(-)

diff --git a/manifest b/manifest
index 674bde4af7..79fd10745a 100644
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Activate\stest\scases\sfor\snew\sjournal\sformat.\s(CVS\s1687)
-D 2004-06-25T06:23:23
+C Add\sa\scomment\son\sthe\simplementation\sof\ssqlite3OsLock().\sNo\scode\schanges.\s(CVS\s1688)
+D 2004-06-25T07:21:28
 F Makefile.in cb7a9889c38723f72b2506c4236ff30a05ff172b
 F Makefile.linux-gcc a9e5a0d309fa7c38e7c14d3ecf7690879d3a5457
 F README f1de682fbbd94899d50aca13d387d1b3fd3be2dd
@@ -46,11 +46,11 @@ F src/os_mac.c 3d31e26be1411acfb7961033098631b4f3486fdf
 F src/os_mac.h 51d2445f47e182ed32d3bd6937f81070c6fd9bd4
 F src/os_test.c ef353f73a2ad85a239d7a77c4a5df2e1377f3848
 F src/os_test.h 6a26a4978492e4bbdbf385554958418ff02db162
-F src/os_unix.c 39e73ed02fc992a6bfc52200ea26704633412cc0
+F src/os_unix.c 63608cd3dd4dd71a91329d35557bb0c0820d18fc
 F src/os_unix.h 00c1f82b526ab2fb7ee5ddd555ea4ed68363c93a
 F src/os_win.c 84549f6cc815237533c5d0eb3697352b03478d96
 F src/os_win.h babd4e912967c6b09088cfe38a45e8005a07ba44
-F src/pager.c 6e3539f1ca18b0b2af9db8e28fd84d5f84115f5b
+F src/pager.c 706e810f8cad58b6800a1b7357e6e91c8d2bb52a
 F src/pager.h bc58d32a9dee464f7268fb68652c130a4216e438
 F src/parse.y 097438674976355a10cf177bd97326c548820b86
 F src/pragma.c 0750e1c360647dbe0a991f16133b0fe5e42e5039
@@ -229,7 +229,7 @@ F www/tclsqlite.tcl 19191cf2a1010eaeff74c51d83fd5f5a4d899075
 F www/vdbe.tcl 59288db1ac5c0616296b26dce071c36cb611dfe9
 F www/version3.tcl 563ba3ac02f64da27ab17f3edbe8e56bfd0293fb
 F www/whentouse.tcl a8335bce47cc2fddb07f19052cb0cb4d9129a8e4
-P 504246a18daca794473b17a7874096f1ec8648ee
-R f017ffd3003f05168cbc5b7d99000fb4
+P 197d00d6a6a440848a0b4710157272558868221c
+R 6345095e6a5c3dcc536a7580feb58513
 U danielk1977
-Z 29d59bf15a42f73cfe80f868d9fac7ef
+Z 2fac742bcbc86b6b2d476d24d96d81ed
diff --git a/manifest.uuid b/manifest.uuid
index e9cc389d09..3eee7af51e 100644
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-197d00d6a6a440848a0b4710157272558868221c
\ No newline at end of file
+084f3fffbdeb1e2b375817ae1111b867c9d32559
\ No newline at end of file
diff --git a/src/os_unix.c b/src/os_unix.c
index e707835f1e..1688c458b5 100644
--- a/src/os_unix.c
+++ b/src/os_unix.c
@@ -696,6 +696,44 @@ int sqlite3OsCheckReservedLock(OsFile *id){
 ** routine to lower a locking level.
 */
 int sqlite3OsLock(OsFile *id, int locktype){
+  /* The following describes the implementation of the various locks and
+  ** lock transitions in terms of the POSIX advisory shared and exclusive
+  ** lock primitives (called read-locks and write-locks below, to avoid
+  ** confusion with SQLite lock names). The algorithms are complicated
+  ** slightly in order to be compatible with windows systems simultaneously
+  ** accessing the same database file, in case that is ever required.
+  **
+  ** Symbols defined in os.h indentify the 'pending byte' and the 'reserved
+  ** byte', each single bytes at well known offsets, and the 'shared byte
+  ** range', a range of 510 bytes at a well known offset.
+  **
+  ** To obtain a SHARED lock, a read-lock is obtained on the 'pending
+  ** byte'.  If this is successful, a random byte from the 'shared byte
+  ** range' is read-locked and the lock on the 'pending byte' released.
+  **
+  ** A process may only obtain a RESERVED lock after it has a SHARED lock
+  ** (the sqlite3OsLock() routine will try to obtain this lock
+  ** automatically if it is not already held). A RESERVED lock is
+  ** implemented by grabbing a write-lock on the 'reserved byte'. 
+  **
+  ** A process may only obtain a PENDING lock after it has obtained a
+  ** SHARED lock (done automatically by sqlite3OsLock()). A PENDING lock is
+  ** implemented by obtaining a write-lock on the 'pending byte'. This
+  ** ensures that no new SHARED locks can be obtained, but existing SHARED
+  ** locks are allowed to persist. A process does not have to obtain a
+  ** RESERVED lock on the way to a PENDING lock. This property is used by
+  ** the algorithm for rolling back a journal file after a crash.
+  **
+  ** An EXCLUSIVE lock is implemented by obtaining a write-lock on the
+  ** entire 'shared byte range'. Since all other locks require a read-lock
+  ** on one of the bytes within this range, this ensures that no other
+  ** locks are held on the database. 
+  **
+  ** The reason a single byte cannot be used instead of the 'shared byte
+  ** range' is that some versions of windows do not support read-locks. By
+  ** locking a random byte from a range, concurrent SHARED locks may exist
+  ** even if the locking primitive used is always a write-lock.
+  */
   int rc = SQLITE_OK;
   struct lockInfo *pLock = id->pLock;
   struct flock lock;
diff --git a/src/pager.c b/src/pager.c
index ab6327a1ba..aedf304d38 100644
--- a/src/pager.c
+++ b/src/pager.c
@@ -18,7 +18,7 @@
 ** file simultaneously, or one process from reading the database while
 ** another is writing.
 **
-** @(#) $Id: pager.c,v 1.139 2004/06/25 06:23:23 danielk1977 Exp $
+** @(#) $Id: pager.c,v 1.140 2004/06/25 07:21:28 danielk1977 Exp $
 */
 #include "os.h"         /* Must be first to enable large file support */
 #include "sqliteInt.h"
@@ -475,7 +475,7 @@ static int seekJournalHdr(Pager *pPager){
 ** - 4 bytes: Initial database page count.
 ** - 4 bytes: Sector size used by the process that wrote this journal.
 ** 
-** Followed by (JOURNAL_HDR_SZ - 20) bytes of unused space.
+** Followed by (JOURNAL_HDR_SZ - 24) bytes of unused space.
 */
 static int writeJournalHdr(Pager *pPager){