m4_comment([$Id: cam_conv.so,v 10.14 2003/10/18 19:16:02 bostic Exp $])m4_ref_title(Locking Subsystem,    m4_cam locking conventions,    m4_cam @locking conventions, lock/twopl, lock/am_conv)m4_p([dnlThe m4_cam product has a simple set of conventions for locking.  Itprovides multiple-reader/single-writer semantics, but not per-pagelocking or transaction recoverability.  As such, it does its lockingentirely in the m4_db interface layer.])m4_p([dnlThe object it locks is the file, identified by its unique file number.The locking matrix is not one of the two standard lock modes, instead,we use a four-lock set, consisting of the following:])m4_tagbeginm4_tag(DB_LOCK_NG, [not granted (always 0)])m4_tagns(DB_LOCK_READ, [read (shared)])m4_tagns(DB_LOCK_WRITE, [write (exclusive)])m4_tagns(DB_LOCK_IWRITE, [intention-to-write (shared with NG and READ, but conflicts with WRITE and IWRITE)])m4_tagendm4_p([dnlThe IWRITE lock is used for cursors that will be used for updating(IWRITE locks are implicitly obtained for write operations through them4_db handles, for example, m4_ref(dbh_put) or m4_ref(dbh_del)).  Whilethe cursor is reading, the IWRITE lock is held; but as soon as thecursor is about to modify the database, the IWRITE is upgraded to aWRITE lock.  This upgrade blocks until all readers have exited thedatabase.  Because only one IWRITE lock is allowed at any one time, notwo cursors can ever try to upgrade to a WRITE lock at the same time,and therefore deadlocks are prevented, which is essential because m4_camdoes not include deadlock detection and recovery.])m4_p([dnlApplications that need to lock compatibly with m4_cam must obey thefollowing rules:])m4_nlistbeginm4_nlist([Use only lock modes DB_LOCK_NG, DB_LOCK_READ, DB_LOCK_WRITE,DB_LOCK_IWRITE.])m4_nlist([Never attempt to acquire a WRITE lock on an object that isalready locked with a READ lock.])m4_nlistendm4_page_footer