Return to vfs-shm.txt CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / sqlite3 / doc

sqlite3

    1: The 5 states of an historical rollback lock as implemented by the
    2: xLock, xUnlock, and xCheckReservedLock methods of the sqlite3_io_methods
    3: objec are:
    4: 
    5:    UNLOCKED
    6:    SHARED
    7:    RESERVED
    8:    PENDING
    9:    EXCLUSIVE
   10: 
   11: The wal-index file has a similar locking hierarchy implemented using
   12: the xShmLock method of the sqlite3_vfs object, but with 7
   13: states.  Each connection to a wal-index file must be in one of
   14: the following 7 states:
   15: 
   16:    UNLOCKED
   17:    READ
   18:    READ_FULL
   19:    WRITE
   20:    PENDING
   21:    CHECKPOINT
   22:    RECOVER
   23: 
   24: These roughly correspond to the 5 states of a rollback lock except
   25: that SHARED is split out into 2 states: READ and READ_FULL and
   26: there is an extra RECOVER state used for wal-index reconstruction.
   27: 
   28: The meanings of the various wal-index locking states is as follows:
   29: 
   30:    UNLOCKED    - The wal-index is not in use.
   31: 
   32:    READ        - Some prefix of the wal-index is being read. Additional
   33:                  wal-index information can be appended at any time.  The
   34:                  newly appended content will be ignored by the holder of
   35:                  the READ lock.
   36: 
   37:    READ_FULL   - The entire wal-index is being read.  No new information
   38:                  can be added to the wal-index.  The holder of a READ_FULL
   39:                  lock promises never to read pages from the database file
   40:                  that are available anywhere in the wal-index.
   41: 
   42:    WRITE       - It is OK to append to the wal-index file and to adjust
   43:                  the header to indicate the new "last valid frame".
   44: 
   45:    PENDING     - Waiting on all READ locks to clear so that a
   46:                  CHECKPOINT lock can be acquired.
   47: 
   48:    CHECKPOINT  - It is OK to write any WAL data into the database file
   49:                  and zero the last valid frame field of the wal-index
   50:                  header.  The wal-index file itself may not be changed
   51:                  other than to zero the last valid frame field in the
   52:                  header.
   53: 
   54:    RECOVER     - Held during wal-index recovery.  Used to prevent a
   55:                  race if multiple clients try to recover a wal-index at
   56:                  the same time.
   57:    
   58: 
   59: A particular lock manager implementation may coalesce one or more of 
   60: the wal-index locking states, though with a reduction in concurrency.
   61: For example, an implemention might implement only exclusive locking,
   62: in which case all states would be equivalent to CHECKPOINT, meaning that 
   63: only one reader or one writer or one checkpointer could be active at a 
   64: time.  Or, an implementation might combine READ and READ_FULL into 
   65: a single state equivalent to READ, meaning that a writer could
   66: coexist with a reader, but no reader or writers could coexist with a
   67: checkpointer.
   68: 
   69: The lock manager must obey the following rules:
   70: 
   71: (1)  A READ cannot coexist with CHECKPOINT.
   72: (2)  A READ_FULL cannot coexist with WRITE.
   73: (3)  None of WRITE, PENDING, CHECKPOINT, or RECOVER can coexist.
   74: 
   75: The SQLite core will obey the next set of rules.  These rules are
   76: assertions on the behavior of the SQLite core which might be verified
   77: during testing using an instrumented lock manager.
   78: 
   79: (5)  No part of the wal-index will be read without holding either some
   80:      kind of SHM lock or an EXCLUSIVE lock on the original database.
   81:      The original database is the file named in the 2nd parameter to
   82:      the xShmOpen method.
   83: 
   84: (6)  A holder of a READ_FULL will never read any page of the database
   85:      file that is contained anywhere in the wal-index.
   86: 
   87: (7)  No part of the wal-index other than the header will be written nor
   88:      will the size of the wal-index grow without holding a WRITE or
   89:      an EXCLUSIVE on the original database file.
   90: 
   91: (8)  The wal-index header will not be written without holding one of
   92:      WRITE, CHECKPOINT, or RECOVER on the wal-index or an EXCLUSIVE on
   93:      the original database files.
   94: 
   95: (9)  A CHECKPOINT or RECOVER must be held on the wal-index, or an
   96:      EXCLUSIVE on the original database file, in order to reset the 
   97:      last valid frame counter in the header of the wal-index back to zero.
   98: 
   99: (10) A WRITE can only increase the last valid frame pointer in the header.
  100: 
  101: The SQLite core will only ever send requests for UNLOCK, READ, WRITE,
  102: CHECKPOINT, or RECOVER to the lock manager.   The SQLite core will never
  103: request a READ_FULL or PENDING lock though the lock manager may deliver
  104: those locking states in response to READ and CHECKPOINT requests,
  105: respectively, if and only if the requested READ or CHECKPOINT cannot
  106: be delivered.
  107: 
  108: The following are the allowed lock transitions:
  109: 
  110:        Original-State     Request         New-State
  111:        --------------     ----------      ----------
  112: (11a)  UNLOCK             READ            READ
  113: (11b)  UNLOCK             READ            READ_FULL
  114: (11c)  UNLOCK             CHECKPOINT      PENDING
  115: (11d)  UNLOCK             CHECKPOINT      CHECKPOINT
  116: (11e)  READ               UNLOCK          UNLOCK
  117: (11f)  READ               WRITE           WRITE
  118: (11g)  READ               RECOVER         RECOVER
  119: (11h)  READ_FULL          UNLOCK          UNLOCK
  120: (11i)  READ_FULL          WRITE           WRITE
  121: (11j)  READ_FULL          RECOVER         RECOVER
  122: (11k)  WRITE              READ            READ
  123: (11l)  PENDING            UNLOCK          UNLOCK
  124: (11m)  PENDING            CHECKPOINT      CHECKPOINT
  125: (11n)  CHECKPOINT         UNLOCK          UNLOCK
  126: (11o)  RECOVER            READ            READ
  127: 
  128: These 15 transitions are all that needs to be supported.  The lock
  129: manager implementation can assert that fact.  The other 27 possible
  130: transitions among the 7 locking states will never occur.