1# Wal-Mode Blocking Locks 2 3On some Unix-like systems, SQLite may be configured to use POSIX blocking locks 4by: 5 6 * building the library with SQLITE\_ENABLE\_SETLK\_TIMEOUT defined, and 7 * configuring a timeout in ms using the sqlite3\_busy\_timeout() API. 8 9Blocking locks may be advantageous as (a) waiting database clients do not 10need to continuously poll the database lock, and (b) using blocking locks 11facilitates transfer of OS priority between processes when a high priority 12process is blocked by a lower priority one. 13 14Only read/write clients use blocking locks. Clients that have read-only access 15to the \*-shm file nevery use blocking locks. 16 17Threads or processes that access a single database at a time never deadlock as 18a result of blocking database locks. But it is of course possible for threads 19that lock multiple databases simultaneously to do so. In most cases the OS will 20detect the deadlock and return an error. 21 22## Wal Recovery 23 24Wal database "recovery" is a process required when the number of connected 25database clients changes from zero to one. In this case, a client is 26considered to connect to the database when it first reads data from it. 27Before recovery commences, an exclusive WRITER lock is taken. 28 29Without blocking locks, if two clients attempt recovery simultaneously, one 30fails to obtain the WRITER lock and either invokes the busy-handler callback or 31returns SQLITE\_BUSY to the user. With blocking locks configured, the second 32client blocks on the WRITER lock. 33 34## Database Readers 35 36Usually, read-only are not blocked by any other database clients, so they 37have no need of blocking locks. 38 39If a read-only transaction is being opened on a snapshot, the CHECKPOINTER 40lock is required briefly as part of opening the transaction (to check that a 41checkpointer is not currently overwriting the snapshot being opened). A 42blocking lock is used to obtain the CHECKPOINTER lock in this case. A snapshot 43opener may therefore block on and transfer priority to a checkpointer in some 44cases. 45 46## Database Writers 47 48A database writer must obtain the exclusive WRITER lock. It uses a blocking 49lock to do so if any of the following are true: 50 51 * the transaction is an implicit one consisting of a single DML or DDL 52 statement, or 53 * the transaction is opened using BEGIN IMMEDIATE or BEGIN EXCLUSIVE, or 54 * the first SQL statement executed following the BEGIN command is a DML or 55 DDL statement (not a read-only statement like a SELECT). 56 57In other words, in all cases except when an open read-transaction is upgraded 58to a write-transaction. In that case a non-blocking lock is used. 59 60## Database Checkpointers 61 62Database checkpointers takes the following locks, in order: 63 64 * The exclusive CHECKPOINTER lock. 65 * The exclusive WRITER lock (FULL, RESTART and TRUNCATE only). 66 * Exclusive lock on read-mark slots 1-N. These are immediately released after being taken. 67 * Exclusive lock on read-mark 0. 68 * Exclusive lock on read-mark slots 1-N again. These are immediately released 69 after being taken (RESTART and TRUNCATE only). 70 71All of the above use blocking locks. 72 73## Summary 74 75With blocking locks configured, the only cases in which clients should see an 76SQLITE\_BUSY error are: 77 78 * if the OS does not grant a blocking lock before the configured timeout 79 expires, and 80 * when an open read-transaction is upgraded to a write-transaction. 81 82In all other cases the blocking locks implementation should prevent clients 83from having to handle SQLITE\_BUSY errors and facilitate appropriate transfer 84of priorities between competing clients. 85 86Clients that lock multiple databases simultaneously must be wary of deadlock. 87 88 89