A few more comment changes. No code alterations. (CVS 1689)

FossilOrigin-Name: b68b4a4262c2ab60f9a7cc0c206b9db207f86933

manifest

@@ -1,5 +1,5 @@
-C Add\sa\scomment\son\sthe\simplementation\sof\ssqlite3OsLock().\sNo\scode\schanges.\s(CVS\s1688)
+C A\sfew\smore\scomment\schanges.\sNo\scode\salterations.\s(CVS\s1689)
-D 2004-06-25T07:21:28
+D 2004-06-25T08:32:26
 F Makefile.in cb7a9889c38723f72b2506c4236ff30a05ff172b
 F Makefile.linux-gcc a9e5a0d309fa7c38e7c14d3ecf7690879d3a5457
 F README f1de682fbbd94899d50aca13d387d1b3fd3be2dd
@@ -40,17 +40,17 @@ F src/insert.c d99ffe87e1e1397f4233afcd06841d52d6b17b18
 F src/legacy.c ad23746f15f67e34577621b1875f639c94839e1f
 F src/main.c 2a4f3fe32ee6357b5b914ab5e2bd0979202570f4
 F src/md5.c 7ae1c39044b95de2f62e066f47bb1deb880a1070
-F src/os.h 2f5ea879b784bc82aac8022a3e8fe00b73c83d67
+F src/os.h d1780e0db95cad01f213d48da22ab490eb4fd345
 F src/os_common.h ba1b7306e16e2091718f2c48db0fe6c1d7a31bb8
 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 63608cd3dd4dd71a91329d35557bb0c0820d18fc
+F src/os_unix.c bd62e20d3abfb96c41fe737715b328d1dbb52bf7
 F src/os_unix.h 00c1f82b526ab2fb7ee5ddd555ea4ed68363c93a
 F src/os_win.c 84549f6cc815237533c5d0eb3697352b03478d96
 F src/os_win.h babd4e912967c6b09088cfe38a45e8005a07ba44
-F src/pager.c 706e810f8cad58b6800a1b7357e6e91c8d2bb52a
+F src/pager.c 65e1b2ed257567016cbc1777378322d9975dd9fd
 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 197d00d6a6a440848a0b4710157272558868221c
+P 084f3fffbdeb1e2b375817ae1111b867c9d32559
-R 6345095e6a5c3dcc536a7580feb58513
+R 3d04f41857d7d71eac91c498ab85aa4a
 U danielk1977
-Z 2fac742bcbc86b6b2d476d24d96d81ed
+Z 3b801fb007c493686ca074ae1ca89a83

manifest.uuid

@@ -1 +1 @@
-084f3fffbdeb1e2b375817ae1111b867c9d32559
+b68b4a4262c2ab60f9a7cc0c206b9db207f86933

src/os.h

@@ -85,6 +85,19 @@
 
 /*
 ** The following values may be passed as the second argument to
+** sqlite3OsLock(). The various locks exhibit the following semantics:
+**
+** SHARED:    Any number of processes may hold a SHARED lock simultaneously.
+** RESERVED:  A single process may hold a RESERVED lock on a file at
+**            any time. Other processes may hold and obtain new SHARED locks.
+** PENDING:   A single process may hold a PENDING lock on a file at
+**            any one time. Existing SHARED locks may persist, but no new
+**            SHARED locks may be obtained by other processes.
+** EXCLUSIVE: An EXCLUSIVE lock precludes all other locks.
+**
+** PENDING_LOCK may not be passed directly to sqlite3OsLock(). Instead, a
+** process that requests an EXCLUSIVE lock may actually obtain a PENDING
+** lock. This can be upgraded to an EXCLUSIVE lock by a subsequent call to
 ** sqlite3OsLock().
 */
 #define NO_LOCK         0

src/os_unix.c

@@ -711,23 +711,23 @@ int sqlite3OsLock(OsFile *id, int locktype){
   ** 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
+  ** A process may only obtain a RESERVED lock after it has a SHARED lock.
-  ** (the sqlite3OsLock() routine will try to obtain this lock
+  ** A RESERVED lock is implemented by grabbing a write-lock on the
-  ** automatically if it is not already held). A RESERVED lock is
+  ** 'reserved byte'. 
-  ** 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
+  ** SHARED lock. A PENDING lock is implemented by obtaining a write-lock
-  ** implemented by obtaining a write-lock on the 'pending byte'. This
+  ** on the 'pending byte'. This ensures that no new SHARED locks can be
-  ** ensures that no new SHARED locks can be obtained, but existing SHARED
+  ** obtained, but existing SHARED locks are allowed to persist. A process
-  ** locks are allowed to persist. A process does not have to obtain a
+  ** does not have to obtain a RESERVED lock on the way to a PENDING lock.
-  ** RESERVED lock on the way to a PENDING lock. This property is used by
+  ** This property is used by the algorithm for rolling back a journal file
-  ** the algorithm for rolling back a journal file after a crash.
+  ** after a crash.
   **
-  ** An EXCLUSIVE lock is implemented by obtaining a write-lock on the
+  ** An EXCLUSIVE lock, obtained after a PENDING lock is held, is
-  ** entire 'shared byte range'. Since all other locks require a read-lock
+  ** implemented by obtaining a write-lock on the entire 'shared byte
-  ** on one of the bytes within this range, this ensures that no other
+  ** range'. Since all other locks require a read-lock on one of the bytes
-  ** locks are held on the database. 
+  ** 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

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.140 2004/06/25 07:21:28 danielk1977 Exp $
+** @(#) $Id: pager.c,v 1.141 2004/06/25 08:32:26 danielk1977 Exp $
 */
 #include "os.h"         /* Must be first to enable large file support */
 #include "sqliteInt.h"
@@ -1952,7 +1952,17 @@ int sqlite3pager_get(Pager *pPager, Pgno pgno, void **ppPage){
     ){
        int rc;
 
-       /* Get an EXCLUSIVE lock on the database file. */
+       /* Get an EXCLUSIVE lock on the database file. At this point it is
+       ** important that a RESERVED lock is not obtained on the way to the
+       ** EXCLUSIVE lock. If it were, another process might open the
+       ** database file, detect the RESERVED lock, and conclude that the
+       ** database is safe to read while this process is still rolling it 
+       ** back.
+       ** 
+       ** Because the intermediate RESERVED lock is not requested, the
+       ** second process will get to this point in the code and fail to
+       ** obtain it's own EXCLUSIVE lock on the database file.
+       */
        rc = sqlite3OsLock(&pPager->fd, EXCLUSIVE_LOCK);
        if( rc!=SQLITE_OK ){
          sqlite3OsUnlock(&pPager->fd, NO_LOCK);