Annotation of embedaddon/sqlite3/doc/vfs-shm.txt, revision 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.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to vfs-shm.txt CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / sqlite3 / doc