Return to vfs-shm.txt CVS log

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

Annotation of embedaddon/sqlite3/doc/vfs-shm.txt, revision 1.1.1.1

1.1       misho       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.