Java Doc for BTreeLockingPolicy.java in  » Database-DBMS » db-derby-10.2 » org » apache » derby » impl » store » access » btree » Java Source Code / Java DocumentationJava Source Code and Java Documentation

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.

Given the current latched page and slot number, lock the logically previous key in the table.

If this routine returns true all locks were acquired while maintaining the latch on leaf.

Logically lock the record id's on a leaf page.

When reclaiming deleted rows during split need to get an exclusive scan lock on the page, which will mean there are no other scans positioned on the page.

Lock the row at the given slot (or the previous row if slot is 0). Get the scan lock on the page if "request_scan_lock" is true.

If this routine returns true all locks were acquired while maintaining the latch on leaf.

Given the current latched page and slot number, lock the logically previous key in the table. There are 3 cases:

slotnumber > 1 - just lock (slotnumber - 1) (slotnumber == 1) && (leftmost leaf) - this is the first key in the table, so lock a "magic" FIRSTKEY. (slotnumber == 1) && !(leftmost leaf)- traverse left in the tree looking for a previous key.

On successful return from this routine appropriate locking will have been done. All locks and latches are requested nowait, if any lock/latch cannot be granted this routine releases the current_leaf latch and any latches it may have acquired and returns "false."

All extra latches that may have been gotten will have been released.

This routine will find the "previous row" to the (current_leaf, current_slot), walking left in the tree as necessary, and first request the lock on that row NOWAIT. If that lock can not be granted, then it will release all latches that it has acquired up to that point including the latched current_leaf passed into the routine, and request the lock WAIT. Once the lock has been granted the routine will return and it is up to the caller to research the tree to find where the row may have ended up.

If routine returns true, lock was granted NOWAIT, current leaf remains latched, and was never unlatched. If routine returns false, lock was granted WAIT, current leaf is not latched, row may have moved in the btree so caller must research to find the row.
Parameters:
  btree - The conglomerate we are locking.
Parameters:
  current_leaf - Latched current leaf where "current" key is.
Parameters:
  current_slot - The slot of row on "current_leaf"
Parameters:
  lock_template - Empty full template row, to read row into.
Parameters:
  open_btree - The open_btree to associate latches with - used if routine has to scan backward.
Parameters:
  lock_operation - For what operation are we requesting the lock, this should be one of the following 4 options:LOCK_READ [read lock], (LOCK_INS | LOCK_UPD) [ lock for insert], (LOCK_INSERT_PREVKEY | LOCK_UPD) [lock for previous key to insert],(LOCK_UPD) [lock for delete or replace]
Parameters:
  lock_duration - For what duration should the lock be held,if INSTANT_DURATION, then the routine willguarantee that lock was acquired while holdingthe latch, but then immediately release thelock. If COMMIT_DURATION or MANUAL_DURATIONthen the lock be held when routine returnssuccessfully.
exception:
  StandardException - Standard exception policy.

Lock a btree row, enforcing the standard lock/latch protocol. On return the row is locked. Return status indicates if the lock was waited for, which will mean a latch was dropped while waiting. In general a false status means that the caller will either have to research the tree unless some protocol has been implemented that insures that the row will not have moved while the latch was dropped.

This routine request a row lock NOWAIT on the in-memory row "current_row.". If the lock is granted the routine will return true. If the lock cannot be granted NOWAIT, then the routine will release the latch on "current_leaf" (if current_leaf is non-null) and "aux_leaf" (if aux_leaf is non-null), and then it will request a WAIT lock on the row.
Parameters:
  btree - The conglomerate we are locking.
Parameters:
  current_leaf - If non-null, this leaf is unlatched if the routine has to wait on the lock.
Parameters:
  aux_leaf - If non-null, this leaf is unlatched if the routine has to wait on the lock.
Parameters:
  current_row - In memory, objectified "current" row.
Parameters:
  lock_operation - For what operation are we requesting the lock, this should be one of the following 4 options:LOCK_READ [read lock], (LOCK_INS | LOCK_UPD) [ lock for insert], (LOCK_INSERT_PREVKEY | LOCK_UPD) [lock for previous key to insert],(LOCK_UPD) [lock for delete or replace]
exception:
  StandardException - Standard exception policy.

If this routine returns true all locks were acquired while maintaining the latch on leaf. If this routine returns false, locks may or may not have been acquired, and the routine should be called again after the client has researched the tree to reget the latch on the appropriate page. Whether locks were acquired without releasing latch on leaf.
Parameters:
  btree - the conglomerate info.
Parameters:
  leaf - The control row of the current leaf to lock.
Parameters:
  slot - The slot position of the row to lock.
Parameters:
  lock_template - A scratch area to use to read in rows.
Parameters:
  lock_operation - For what operation are we requesting the lock, this should be one of the following 4 options:LOCK_READ [read lock], (LOCK_INS | LOCK_UPD) [ lock for insert], (LOCK_INSERT_PREVKEY | LOCK_UPD) [lock for previous key to insert],(LOCK_UPD) [lock for delete or replace]
exception:
  StandardException - Standard exception policy.

Logically lock the record id's on a leaf page. This protocol is used by splits/row purgers and scans to coordinate between themselves.

Anyone who wants to either move rows off of a btree page or, purge them from existence must first call this routine with "forUpdate" true. This will result in a lock request which will block on other processes which cannot work if rows move off the page or disappear. It is expected that the this routine will only be called for update by very short term internal transactions which will commit immediately after doing their work and give up the exclusive lock quickly.

Currently scans can position themselves in one of 2 ways, either by saving the record handle of a record when they give up the latch on the page, or by saving the entire row. If they save the record handle then they must call this routine with "forUpdate" false, to get a lock which will protect the record handle they are using from moving off the page or disapearing. This is also why aborts of inserts must be done by marking the rows deleted, rather than purging them. It is expected that scanner's will release this lock once they move off the page they are looking at. They do this by calling unlockScan().

This lock enforces the same lock/latch protocol as btree row locks. On return the lock has been obtained. Return status indicates if the lock was waited for, which will mean a latch(s) were dropped while waiting. In general a false status means that the caller will either have to research the tree unless some protocol has been implemented that insures that the row will not have moved while the latch was dropped.

This routine requests a special row on the RECORD_ID_PROTECTION_HANDLE row id. If the lock is granted the routine will return true. If the lock cannot be granted NOWAIT, then the routine will release the latch on "current_leaf" and "aux_control_row" (if aux_control_row is non-null), and then it will request a WAIT lock on the row.
Parameters:
  current_leaf - The lock is associated with this page in thebtree. This control row is unlatched if theroutine has to wait on the lock.
Parameters:
  aux_control_row - If non-null, this control row is unlatched if the routine has to wait on the lock.
Parameters:
  forUpdate - Whether to wait for lock.
Parameters:
  lock_operation - For what operation are we requesting the lock, this should be one of the following 4 options:LOCK_READ [read lock], (LOCK_INS | LOCK_UPD) [ lock for insert], (LOCK_INSERT_PREVKEY | LOCK_UPD) [lock for previous key to insert],(LOCK_UPD) [lock for delete or replace]
exception:
  StandardException - Standard exception policy.

Request an exclusive lock on the row located at the given slot, NOWAIT. Return true if the lock is granted, otherwise false.

Parameters:
  open_btree - The conglomerate we are locking.
Parameters:
  leaf - The leaf page with the row to lock.
Parameters:
  template - Empty full template row, to read row into.
Parameters:
  slot_no - The slot of row on "current_leaf"
exception:
  StandardException - Standard exception policy.

When reclaiming deleted rows during split need to get an exclusive scan lock on the page, which will mean there are no other scans positioned on the page. If there are other scans positioned, just give up on reclaiming space now. true if lock was granted nowait, else false and not lock wasgranted.
exception:
  StandardException - Standard exception policy.

Lock the row at the given slot (or the previous row if slot is 0). Get the scan lock on the page if "request_scan_lock" is true.

If this routine returns true all locks were acquired while maintaining the latch on leaf. If this routine returns false, locks may or may not have been acquired, and the routine should be called again after the client has researched the tree to reget the latch on the appropriate page. (p> As a side effect stores the value of the record handle of the current scan lock. Whether locks were acquired without releasing latch on leaf.
Parameters:
  open_btree - The open_btree to associate latches with - used if routine has to scan backward.
Parameters:
  btree - the conglomerate info.
Parameters:
  pos - Description of position of row to lock.
Parameters:
  request_scan_lock - Whether to request the page scan lock, shouldonly be requested once per page in the scan.
Parameters:
  lock_template - A scratch area to use to read in rows.
Parameters:
  previous_key_lock - Is this a previous key lock call?
Parameters:
  forUpdate - Is the scan for update or for read only.
Parameters:
  lock_operation - For what operation are we requesting the lock, this should be one of the following 4 options:LOCK_READ [read lock], (LOCK_INS | LOCK_UPD) [ lock for insert], (LOCK_INSERT_PREVKEY | LOCK_UPD) [lock for previous key to insert],(LOCK_UPD) [lock for delete or replace]
exception:
  StandardException - Standard exception policy.

Parameters:
  page_number - page number of page that lockScan was called on.