From: dan Date: Sat, 17 Apr 2010 18:50:27 +0000 (+0000) Subject: Add some comments regarding file-locks to log.c. X-Git-Tag: version-3.7.2~455^2~70 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=54934f4689ee181d366987cfe746dc2ed79c35be;p=thirdparty%2Fsqlite.git Add some comments regarding file-locks to log.c. FossilOrigin-Name: 9d51c3b754f0b94fea5ef3d669ad583b93b2b024 --- diff --git a/manifest b/manifest index 628fe3b0e0..e3133fe899 100644 --- a/manifest +++ b/manifest @@ -1,5 +1,5 @@ -C Do\snot\ssync\sany\sfiles\sin\swal\smode\sif\s"PRAGMA\ssynchronous=off"\sis\sset.\sIf\sfiles\sare\ssynced,\spass\seither\sSQLITE_SYNC_FULL\sor\sSQLITE_SYNC_NORMAL\sto\sthe\sxSync()\scallback\sas\sconfigured\sby\s"PRAGMA\sfullfsync". -D 2010-04-17T17:34:42 +C Add\ssome\scomments\sregarding\sfile-locks\sto\slog.c. +D 2010-04-17T18:50:28 F Makefile.arm-wince-mingw32ce-gcc fcd5e9cd67fe88836360bb4f9ef4cb7f8e2fb5a0 F Makefile.in 4f2f967b7e58a35bb74fb7ec8ae90e0f4ca7868b F Makefile.linux-gcc d53183f4aa6a9192d249731c90dbdffbd2c68654 @@ -131,7 +131,7 @@ F src/journal.c b0ea6b70b532961118ab70301c00a33089f9315c F src/legacy.c a199d7683d60cef73089e892409113e69c23a99f F src/lempar.c 7f026423f4d71d989e719a743f98a1cbd4e6d99e F src/loadext.c 1c7a61ce1281041f437333f366a96aa0d29bb581 -F src/log.c 8bcd490de703a12563c939a59cb4e187a0c67fe3 +F src/log.c fd6631f740b0cf2c8720477a036ffee8ca705c92 F src/log.h 3cfec02156f5db3d233352897a47601930a29955 F src/main.c c0e7192bad5b90544508b241eb2487ac661de890 F src/malloc.c a08f16d134f0bfab6b20c3cd142ebf3e58235a6a @@ -805,7 +805,7 @@ F tool/speedtest2.tcl ee2149167303ba8e95af97873c575c3e0fab58ff F tool/speedtest8.c 2902c46588c40b55661e471d7a86e4dd71a18224 F tool/speedtest8inst1.c 293327bc76823f473684d589a8160bde1f52c14e F tool/vdbe-compress.tcl d70ea6d8a19e3571d7ab8c9b75cba86d1173ff0f -P 43463970f5885fb116588695146f2a56cb22804a -R 0e49b7b76893a9b984350c6fdab0ea9a +P 0ae91b0008b242a47385fc1f295c6b645483ee22 +R a205bea3ab4fa24118ce751726c3c719 U dan -Z ad3f9c0ef28635a13cd67b8f240d7d22 +Z c979f9f88d66076be76b02e7ab3fa216 diff --git a/manifest.uuid b/manifest.uuid index ed4b8c00cd..26af5e1525 100644 --- a/manifest.uuid +++ b/manifest.uuid @@ -1 +1 @@ -0ae91b0008b242a47385fc1f295c6b645483ee22 \ No newline at end of file +9d51c3b754f0b94fea5ef3d669ad583b93b2b024 \ No newline at end of file diff --git a/src/log.c b/src/log.c index a6d7f35440..81f808aa6c 100644 --- a/src/log.c +++ b/src/log.c @@ -103,6 +103,93 @@ struct LogSummary { u32 *aData; /* File body */ }; +/* +** This module uses three different types of file-locks. All are taken +** on the log-summary file. The three types of locks are as follows: +** +** MUTEX: The MUTEX lock is used as a robust inter-process mutex. It +** is held while the log-summary header is modified, and +** sometimes when it is read. It is also held while a new client +** obtains the DMH lock (see below), and while log recovery is +** being run. +** +** DMH: The DMH (Dead Mans Hand mechanism) lock is used to ensure +** that log-recovery is always run following a system restart. +** When it first opens a log-summary file, a process takes a +** SHARED lock on the DMH region. This lock is not released until +** the log-summary file is closed. +** +** The process then attempts to upgrade to an EXCLUSIVE lock. If +** successful, then the contents of the log-summary file are deemed +** suspect and the log-summary header zeroed. This forces the +** first process that reads the log-summary file to run log +** recovery. After zeroing the log-summary header, the process +** downgrades to a SHARED lock on the DMH region. +** +** If the attempt to obtain the EXCLUSIVE lock fails, then the +** process concludes that some other process is already using the +** log-summary file, and it can therefore be trusted. +** +** The procedure described in the previous three paragraphs (taking +** a SHARED lock and then upgrading to an EXCLUSIVE lock to check +** if the process is the only one to have an open connection to the +** log file) is protected by holding the MUTEX lock. This avoids the +** race condition wherein the first two clients connect almost +** simultaneously following a system restart and each prevents +** the other from obtaining the EXCLUSIVE lock. +** +** +** REGION: There are 4 different region locks, regions A, B, C and D. +** Various EXCLUSIVE and SHARED locks on these regions are obtained +** when a client reads, writes or checkpoints the database. +** +** To obtain a reader lock: +** +** 1. Attempt a SHARED lock on regions A and B. +** 2. If step 1 is successful, drop the lock on region B. Or, if +** it is unsuccessful, attempt a SHARED lock on region D. +** 3. Repeat the above until the lock attempt in step 1 or 2 is +** successful. +** +** The reader lock is released when the read transaction is finished. +** +** To obtain a writer lock: +** +** 1. Take (wait for) an EXCLUSIVE lock on regions C and D. +** +** The locks are released after the write transaction is finished +** and, if any frames were committed to the log, the log-summary +** file updated. +** +** To obtain a checkpointer lock: +** +** 1. Take (wait for) an EXCLUSIVE lock on regions B and C. +** 2. Take (wait for) an EXCLUSIVE lock on region A. +** +** Step 1 waits until any existing writer has finished. And forces +** all new readers to become "region D" readers. +** +** Step 2 causes the checkpointer to wait until all existing region A +** readers have finished their transactions. Once the exclusive lock +** on region A has been obtained, only "region D" readers exist. +** These readers are operating on the snapshot at the head of the +** log. As such, the log can be safely copied into the database file +** without interfering with the readers. +** +** Once the checkpoint has finished and the log-summary header +** updated (to indicate the log contents can now be ignored), all +** locks are released. +** +** However, there may still exist region D readers using data in +** the body of the log file, so the log file itself cannot be +** truncated or overwritten until all region D readers have finished. +** That requirement is satisfied, because writers (the clients that +** write to the log file) require an exclusive lock on region D. +** Which they cannot get until all region D readers have finished. +*/ +#define LOG_LOCK_MUTEX 12 +#define LOG_LOCK_DMH 13 +#define LOG_LOCK_REGION 14 /* ** The four lockable regions associated with each log-summary. A connection @@ -115,10 +202,6 @@ struct LogSummary { #define LOG_REGION_C 0x04 #define LOG_REGION_D 0x08 -#define LOG_LOCK_MUTEX 12 -#define LOG_LOCK_DMH 13 -#define LOG_LOCK_REGION 14 - /* ** A single instance of this structure is allocated as part of each ** connection to a database log. All structures associated with the