LockControl (Apache Derby V10.14 Internals)

java.lang.Object
- org.apache.derby.impl.services.locks.LockControl

All Implemented Interfaces:

Control
```
final class LockControl
extends java.lang.Object
implements Control
```
A LockControl contains a reference to the item being locked and doubly linked lists for the granted locks and the waiting locks.
MT - Mutable - Container object : single thread required

Field Summary

Fields
Modifier and Type	Field	Description
`private Lock`	`firstGrant`	This lock control uses an optimistic locking scheme.
`private java.util.List<Lock>`	`granted`
`private Lock`	`lastPossibleSkip`
`private Lockable`	`ref`
`private java.util.List<Lock>`	`waiting`

Constructor Summary

Constructors
Modifier Constructor Description

private LockControl(LockControl copyFrom)

protected LockControl(Lock firstLock, Lockable ref)

Constructors
Modifier	Constructor	Description
`private`	`LockControl(LockControl copyFrom)`
`protected`	`LockControl(Lock firstLock, Lockable ref)`

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`Lock`	`addLock(LockTable ls, CompatibilitySpace compatibilitySpace, java.lang.Object qualifier)`	Add a lock into this control, granted it if possible.
`private void`	`addWaiter(Lock lockItem, LockTable ls)`	Add a lock request to a list of waiters.
`void`	`addWaiters(java.util.Map<java.lang.Object,java.lang.Object> waiters)`	Add the waiters of this lock into this Map object.
`boolean`	`blockedByParent(Lock childLock)`	Returns true if the childLock is blocked because its parent owns a conficting lock.
`ActiveLock`	`firstWaiter()`	Return the first lock in the wait line, null if the line is empty.
`Lock`	`getFirstGrant()`
`java.util.List<Lock>`	`getGranted()`
`(package private) java.util.List<Lock>`	`getGrants()`	Return a Stack of the held locks (Lock objects) on this Lockable.
`Lock`	`getLock(CompatibilitySpace compatibilitySpace, java.lang.Object qualifier)`	Find a granted lock matching this space and qualifier
`Lockable`	`getLockable()`	Return the lockable object controlled by me.
`LockControl`	`getLockControl()`
`(package private) ActiveLock`	`getNextWaiter(ActiveLock item, boolean remove, LockTable ls)`	Get the next waiting lock (if any).
`java.util.List<Lock>`	`getWaiting()`
`protected void`	`giveUpWait(java.lang.Object item, LockTable ls)`	Give up waiting up on a lock
`(package private) void`	`grant(Lock lockItem)`	Grant this lock.
`boolean`	`isEmpty()`
`boolean`	`isGrantable(boolean noWaitersBeforeMe, CompatibilitySpace compatibilitySpace, java.lang.Object qualifier)`	This routine can be called to see if a lock currently on the wait list could be granted.
`protected boolean`	`isUnlocked()`
`private java.lang.Object`	`popFrontWaiter(LockTable ls)`	Remove and return the first lock request from a list of waiters.
`private java.lang.Object`	`removeWaiter(int index, LockTable ls)`	Remove and return the lock request at the given index from a list of waiters.
`private int`	`removeWaiter(java.lang.Object item, LockTable ls)`	Remove and return the given lock request from a list of waiters.
`Control`	`shallowClone()`	make a shallow clone of myself
`boolean`	`unlock(Latch lockInGroup, int unlockCount)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - ref
```
private final Lockable ref
```
  - firstGrant
```
private Lock firstGrant
```
    This lock control uses an optimistic locking scheme. When the first lock on an object is granted it simply sets firstGrant to be that object, removing the need to allocate a list if no other locks are granted before the first lock is release. If a second lock is granted then a list is allocated and the firstGrant lock is moved into the list. Once a list has been created it is always used.
  - granted
```
private java.util.List<Lock> granted
```
  - waiting
```
private java.util.List<Lock> waiting
```
  - lastPossibleSkip
```
private Lock lastPossibleSkip
```
- Constructor Detail
  - LockControl
```
protected LockControl(Lock firstLock,
                      Lockable ref)
```
  - LockControl
```
private LockControl(LockControl copyFrom)
```
- Method Detail
  - getLockControl
```
public LockControl getLockControl()
```
    Specified by:
    
    getLockControl in interface Control
  - isEmpty
```
public boolean isEmpty()
```
    Specified by:
    
    isEmpty in interface Control
  - grant
```
void grant(Lock lockItem)
```
    Grant this lock.
  - unlock
```
public boolean unlock(Latch lockInGroup,
                      int unlockCount)
```
    Specified by:
    
    unlock in interface Control
  - isGrantable
```
public boolean isGrantable(boolean noWaitersBeforeMe,
                           CompatibilitySpace compatibilitySpace,
                           java.lang.Object qualifier)
```
    This routine can be called to see if a lock currently on the wait list could be granted. If this lock has waiters ahead of it then we do not jump over the waiter(s) even if we can be granted. This avoids the first waiter being starved out.
    
    Specified by:
    
    isGrantable in interface Control
  - addLock
```
public Lock addLock(LockTable ls,
                    CompatibilitySpace compatibilitySpace,
                    java.lang.Object qualifier)
```
    Add a lock into this control, granted it if possible. This can be entered in several states.
  - The Lockable is locked (granted queue not empty), and there are no waiters (waiting queue is empty)
  - The Lockable is locked and there are waiters
  - The Lockable is locked and there are waiters and the first is potentially granted
  - The Lockable is unlocked and there are waiters and the first is potentially granted. Logically the item is still locked, it's just that the lock has just been released and the first waker has not woken up yet. This call is never entered when the object is unlocked and there are no waiters. 1) The Lockable has just been unlocked,

isUnlocked
```
protected boolean isUnlocked()
```

firstWaiter
```
public ActiveLock firstWaiter()
```
Return the first lock in the wait line, null if the line is empty.

Specified by:

firstWaiter in interface Control

getNextWaiter

ActiveLock getNextWaiter(ActiveLock item,
                         boolean remove,
                         LockTable ls)

Get the next waiting lock (if any).

getLockable
```
public Lockable getLockable()
```
Return the lockable object controlled by me.

Specified by:

getLockable in interface Control

getFirstGrant
```
public Lock getFirstGrant()
```
Specified by:

getFirstGrant in interface Control

getGranted
```
public java.util.List<Lock> getGranted()
```
Specified by:

getGranted in interface Control

getWaiting
```
public java.util.List<Lock> getWaiting()
```
Specified by:

getWaiting in interface Control

giveUpWait

protected void giveUpWait(java.lang.Object item,
                          LockTable ls)

Give up waiting up on a lock

addWaiters
```
public void addWaiters(java.util.Map<java.lang.Object,java.lang.Object> waiters)
```
Add the waiters of this lock into this Map object.
Each waiting thread gets two entries in the hashtable
1. key=compatibility space - value=ActiveLock
2. key=ActiveLock - value={LockControl for first waiter|ActiveLock of previosue waiter}
Specified by:

addWaiters in interface Control

getGrants
```
java.util.List<Lock> getGrants()
```
Return a Stack of the held locks (Lock objects) on this Lockable.

getLock

public final Lock getLock(CompatibilitySpace compatibilitySpace,
                          java.lang.Object qualifier)

Find a granted lock matching this space and qualifier

Specified by:: getLock in interface Control

blockedByParent
```
public boolean blockedByParent(Lock childLock)
```
Returns true if the childLock is blocked because its parent owns a conficting lock. This code was written to support the fix to DERBY-6554. The only known way that this condition arises is when a write attempt by a nested user transaction is blocked by a read lock held by the main transaction. This only happens while trying to write to SYS.SYSSEQUENCES while managing sequence generators.

shallowClone
```
public Control shallowClone()
```
make a shallow clone of myself

Specified by:

shallowClone in interface Control

addWaiter

private void addWaiter(Lock lockItem,
                       LockTable ls)

Add a lock request to a list of waiters.

Parameters:: lockItem - The lock request; ls - The lock table

popFrontWaiter
```
private java.lang.Object popFrontWaiter(LockTable ls)
```
Remove and return the first lock request from a list of waiters.

Parameters:

ls - The lock table

Returns:

The removed lock request

removeWaiter
```
private java.lang.Object removeWaiter(int index,
                                      LockTable ls)
```
Remove and return the lock request at the given index from a list of waiters.

Parameters:

index - The index at which to remove the lock request

ls - The lock table

Returns:

The removed lock request

removeWaiter
```
private int removeWaiter(java.lang.Object item,
                         LockTable ls)
```
Remove and return the given lock request from a list of waiters.

Parameters:

item - The item to remove

ls - The lock table

Returns:

The number of items removed

Class LockControl

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

ref

firstGrant

granted

waiting

lastPossibleSkip

Constructor Detail

LockControl

LockControl

Method Detail

getLockControl

isEmpty

grant

unlock

isGrantable

addLock

isUnlocked

firstWaiter

getNextWaiter

getLockable

getFirstGrant

getGranted

getWaiting

giveUpWait

addWaiters

getGrants

getLock

blockedByParent

shallowClone

addWaiter

popFrontWaiter

removeWaiter

removeWaiter