doc/wal-lock.md

   1 # Wal-Mode Blocking Locks
   2
   3 On some Unix-like systems, SQLite may be configured to use POSIX blocking locks
   4 by:
   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
   9 Blocking locks may be advantageous as (a) waiting database clients do not
  10 need to continuously poll the database lock, and (b) using blocking locks
  11 facilitates transfer of OS priority between processes when a high priority
  12 process is blocked by a lower priority one.
  13
  14 Only read/write clients use blocking locks. Clients that have read-only access
  15 to the \*-shm file nevery use blocking locks.
  16
  17 Threads or processes that access a single database at a time never deadlock as
  18 a result of blocking database locks. But it is of course possible for threads
  19 that lock multiple databases simultaneously to do so. In most cases the OS will
  20 detect the deadlock and return an error.
  21
  22 ## Wal Recovery
  23
  24 Wal database "recovery" is a process required when the number of connected
  25 database clients changes from zero to one. In this case, a client is
  26 considered to connect to the database when it first reads data from it.
  27 Before recovery commences, an exclusive WRITER lock is taken.
  28
  29 Without blocking locks, if two clients attempt recovery simultaneously, one
  30 fails to obtain the WRITER lock and either invokes the busy-handler callback or
  31 returns SQLITE\_BUSY to the user. With blocking locks configured, the second
  32 client blocks on the WRITER lock.
  33
  34 ## Database Readers
  35
  36 Usually, read-only are not blocked by any other database clients, so they
  37 have no need of blocking locks.
  38
  39 If a read-only transaction is being opened on a snapshot, the CHECKPOINTER
  40 lock is required briefly as part of opening the transaction (to check that a
  41 checkpointer is not currently overwriting the snapshot being opened). A
  42 blocking lock is used to obtain the CHECKPOINTER lock in this case. A snapshot
  43 opener may therefore block on and transfer priority to a checkpointer in some
  44 cases.
  45
  46 ## Database Writers
  47
  48 A database writer must obtain the exclusive WRITER lock. It uses a blocking
  49 lock 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
  57 In other words, in all cases except when an open read-transaction is upgraded
  58 to a write-transaction. In that case a non-blocking lock is used.
  59
  60 ## Database Checkpointers
  61
  62 Database 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
  71 All of the above use blocking locks.
  72
  73 ## Summary
  74
  75 With blocking locks configured, the only cases in which clients should see an
  76 SQLITE\_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
  82 In all other cases the blocking locks implementation should prevent clients
  83 from having to handle SQLITE\_BUSY errors and facilitate appropriate transfer
  84 of priorities between competing clients.
  85
  86 Clients that lock multiple databases simultaneously must be wary of deadlock.
  87
  88