The generic.BTree directory wants to know as little about locking as possible, in order to make the code usuable by multiple implementations. But the generic code will make calls to abstract lock calls implemented by concrete btree implementations. Concrete implementations like B2I understand locking, and needs informatation specific to the implementation to make the lock calls.
This class is created and owned by the concrete application, but is passed into and returned from the generic code when lock calls are made. Concrete implementations which do not need lock calls can just pass a null pointer where a BTreeLockingPolicy is requested.
There are 2 types of lock interfaces, lockScan*() and lockNonScan*().
The lockScan*() interfaces assume that the caller gets a "scan lock" on the page before requesting any row locks on the page. This is either done by makeing a lockScan() call followed by row lock requests, or it can be done in one operation by calling lockScanRow() and requesting the scan lock be obtained before getting the row lock. Upon return from these interfaces the row lock requested is guaranteed to have been obtained on the correct key for the row requested. These interfaces handle the special case of unique indexes where the RowLocation can change while waiting on the lock (see implementation for details), basically the lock is retryed after waiting if the RowLocation has changed.
The lockNonScan*() interfaces assume that no "scan lock" exists. If these routines return that the latch was released while waiting to obtain the lock, then the caller must requeue the lock request after taking appropriate action. This action usually involves researching the tree to make sure that the correct key is locked with latches held. Because no scan lock is held the original row could have disappeared from the table. These interfaces do not handle the special case of unique indexes where the RowLocation can change while waiting on the lock, as the row may disappear when the latch is released to wait on the lock - thus it is necessary that the caller retry the lock if the interface returns that the latch was released.