Add new file doc/wal-lock.md, containing notes on wal-mode blocking locks.

FossilOrigin-Name: c6b1d3a385751633d3ac1853e13d5e847185dd6432fb8b960a4080f61357c08c

diff --git a/doc/wal-lock.md b/doc/wal-lock.md
new file mode 100644 (file)
index 0000000..d74bb88
--- /dev/null
+++ b/doc/wal-lock.md
@@ -0,0 +1,88 @@
+# Wal-Mode Blocking Locks
+
+On some Unix-like systems, SQLite may be configured to use POSIX blocking locks
+by:
+
+  * building the library with SQLITE\_ENABLE\_SETLK\_TIMEOUT defined, and 
+  * configuring a timeout in ms using the sqlite3\_busy\_timeout() API.
+
+Blocking locks may be advantageous as (a) waiting database clients do not
+need to continuously poll the database lock, and (b) using blocking locks
+facilitates transfer of OS priority between processes when a high priority
+process is blocked by a lower priority one.
+
+Only read/write clients use blocking locks. Clients that have read-only access
+to the \*-shm file nevery use blocking locks.
+
+Threads or processes that access a single database at a time never deadlock as
+a result of blocking database locks. But it is of course possible for threads
+that lock multiple databases simultaneously to do so. In most cases the OS will
+detect the deadlock and return an error.
+
+## Wal Recovery
+
+Wal database "recovery" is a process required when the number of connected
+database clients changes from zero to one. In this case, a client is 
+considered to connect to the database when it first reads data from it.
+Before recovery commences, an exclusive WRITER lock is taken. 
+
+Without blocking locks, if two clients attempt recovery simultaneously, one
+fails to obtain the WRITER lock and either invokes the busy-handler callback or
+returns SQLITE\_BUSY to the user. With blocking locks configured, the second
+client blocks on the WRITER lock.
+
+## Database Readers
+
+Usually, read-only are not blocked by any other database clients, so they 
+have no need of blocking locks.
+
+If a read-only transaction is being opened on a snapshot, the CHECKPOINTER
+lock is required briefly as part of opening the transaction (to check that a
+checkpointer is not currently overwriting the snapshot being opened). A
+blocking lock is used to obtain the CHECKPOINTER lock in this case. A snapshot
+opener may therefore block on and transfer priority to a checkpointer in some
+cases.
+
+## Database Writers
+
+A database writer must obtain the exclusive WRITER lock. It uses a blocking
+lock to do so if any of the following are true:
+
+  * the transaction is an implicit one consisting of a single DML or DDL
+    statement, or
+  * the transaction is opened using BEGIN IMMEDIATE or BEGIN EXCLUSIVE, or
+  * the first SQL statement executed following the BEGIN command is a DML or
+    DDL statement (not a read-only statement like a SELECT).
+
+In other words, in all cases except when an open read-transaction is upgraded
+to a write-transaction. In that case a non-blocking lock is used.
+
+## Database Checkpointers
+
+Database checkpointers takes the following locks, in order:
+
+  * The exclusive CHECKPOINTER lock.
+  * The exclusive WRITER lock (FULL, RESTART and TRUNCATE only).
+  * Exclusive lock on read-mark slots 1-N. These are immediately released after being taken.
+  * Exclusive lock on read-mark 0.
+  * Exclusive lock on read-mark slots 1-N again. These are immediately released
+    after being taken (RESTART and TRUNCATE only).
+
+All of the above use blocking locks.
+
+## Summary
+
+With blocking locks configured, the only cases in which clients should see an
+SQLITE\_BUSY error are:
+
+  * if the OS does not grant a blocking lock before the configured timeout
+    expires, and
+  * when an open read-transaction is upgraded to a write-transaction.
+
+In all other cases the blocking locks implementation should prevent clients
+from having to handle SQLITE\_BUSY errors and facilitate appropriate transfer
+of priorities between competing clients.
+
+Clients that lock multiple databases simultaneously must be wary of deadlock.
+
+

diff --git a/manifest b/manifest
index c5528e1a41c3c45666a309fb9f07c5b4801b0f65..1c62e7fa0f9e4b500d565503a58a7639f25781d4 100644 (file)
--- a/manifest
+++ b/manifest
@@ -1,8 +1,9 @@
 B fd5abb1a7b5a55127d5c0d5ff448020d8bccab44e4f5afe1eb88fc19578af735
-C In\sthe\sCLI,\sonly\sinterrupt\stabular\soutputs\sat\sthe\send\sof\sa\sline.\s\sAnd\sprint\n"Interrupt"\son\sa\sline\safter\sstopping\sthe\soutput.
-D 2020-06-16T17:34:40.898
+C Add\snew\sfile\sdoc/wal-lock.md,\scontaining\snotes\son\swal-mode\sblocking\slocks.
+D 2020-06-16T19:51:56.187
 F configure f594931bd7b23dad12db96b81e1dba43b41b30a4560d6eb008014e3d9f1617e8 x
 F configure.ac 13e4ecf89214c3aa0ba099a9e0178f13f03261ace627126737d8cee240ec5c1c
+F doc/wal-lock.md 781726aaba20bafeceb7ba9f91d5c98c6731691b30c954e37cf0b49a053d461d
 F ext/fts3/fts3.c ad3416827315a5bef8d0e23d8e90bf29940fbec23ee78aa0c5d3caed85072dec
 F src/alter.c b8ffe4acd48b4fe793d01901f28fd4f3b037854a0e99f0c977738556c31b9d2b
 F src/btree.c f3a4479b0dba3a59a1d156d973be41fc1ccb3dbdb69151c4c62a791d86c9ffe2
@@ -28,7 +29,7 @@ F test/where.test f5e62453537e5b335b69f3b09f8a02ce3328289fad5d866e25371284b837d7
 F test/whereG.test 9363b2a97d914cb1b81aff5069ef0cf2a071a67e2b604eac6fe9c0114017d9aa
 F test/window1.test 9d7f4990e5b36d95af93b189da4aa75216c6690ce95cced3c8b6d3234be51c2c
 F test/without_rowid3.test 96426a6c9a2a5cf62bbe55ea1ad038eaaf4bf743f40a1ad517233b8e5a3d4339
-P 95379da0e1ad5110648a5b3af24e7caab66a6f1ad6efdf374c83ae4ef1fed515
-R 7e790a0cce062c1755f55b7e661415e2
-U drh
-Z 7c2c29d35a69f3e3cd4c13d57f6827c3
+P f3bd689336fecaa1e2928b826c6aedb0178d322f4633ac429dd1ae6fbc08e7f1
+R 20b349aca00331020aae5b577df5847f
+U dan
+Z 109a0399a3983dd11a4da8f364e04d14

diff --git a/manifest.uuid b/manifest.uuid
index 887f7e7e6edb69a87aed1eab9d4495e281f71478..863cc43bb7b7ab4e226c76a242c3d433360ed03b 100644 (file)
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-f3bd689336fecaa1e2928b826c6aedb0178d322f4633ac429dd1ae6fbc08e7f1
\ No newline at end of file
+c6b1d3a385751633d3ac1853e13d5e847185dd6432fb8b960a4080f61357c08c
\ No newline at end of file