Top Description Inners Fields Constructors Methods
org.apache.derby.impl.services.locks

pack-priv final Class ConcurrentLockSet

extends Object
implements LockTable
Class Inheritance
All Implemented Interfaces
org.apache.derby.impl.services.locks.LockTable
Imports
org.apache.derby.iapi.services.locks.CompatibilitySpace, .Latch, .Lockable, .C_LockFactory, org.apache.derby.shared.common.error.StandardException, org.apache.derby.shared.common.sanity.SanityManager, org.apache.derby.iapi.services.diag.DiagnosticUtil, org.apache.derby.shared.common.reference.Property, .SQLState, java.util.concurrent.atomic.AtomicInteger, java.util.concurrent.locks.Condition, .ReentrantLock, java.util.concurrent.ConcurrentHashMap, java.util.ArrayList, .HashMap, .Enumeration, .Map
A ConcurrentLockSet is a complete lock table which maps Lockables to LockControl objects.

A LockControl contains information about the locks held on a Lockable.
MT - Mutable : All public methods of this class, except addWaiters, are thread safe. addWaiters can only be called from the thread which performs deadlock detection. Only one thread can perform deadlock detection at a time.
The class creates ActiveLock and LockControl objects. LockControl objects are never passed out of this class, All the methods of LockControl are called while holding a ReentrantLock associated with the Lockable controlled by the LockControl, thus providing the single threading that LockControl required. Methods of Lockables are only called by this class or LockControl, and always while holding the corresponding ReentrantLock, thus providing the single threading that Lockable requires.

See Also
LockControl

Nested and Inner Type Summary

Modifier and TypeClass and Description
private static class
ConcurrentLockSet.Entry

Class representing an entry in the lock table.

Field Summary

Modifier and TypeField and Description
private final AtomicInteger
blockCount

private int
deadlockTimeout

Timeout for deadlocks, in ms.

private boolean
deadlockTrace

private final AbstractPool
factory

private final ConcurrentHashMap<Lockable, ConcurrentLockSet.Entry>
locks

Hash table which maps Lockable objects to Locks.

private ArrayList<ConcurrentLockSet.Entry>
seenByDeadlockDetection

List containing all entries seen by the last call to addWaiters().

private int
waitTimeout

Constructor Summary

AccessConstructor and Description
pack-priv
ConcurrentLockSet(AbstractPool factory)

Method Summary

Modifier and TypeMethod and Description
public void
addWaiters(Map<Object, Object>
the map to add the waiters to
waiters)

Implements org.apache.derby.impl.services.locks.LockTable.addWaiters.

Add all waiters in this lock table to a Map object.

public boolean

Returns:

true if someone is blocked, false otherwise
anyoneBlocked()

Implements org.apache.derby.impl.services.locks.LockTable.anyoneBlocked.

Check whether anyone is blocked.

private Object[]

Returns:

an object describing the deadlock
checkDeadlock(ConcurrentLockSet.Entry
the entry in the lock table for the lock request that triggered deadlock detection
entry, ActiveLock
the waiting lock
waitingLock, byte
the reason for waking up the waiter
wakeupReason)

Check whether there is a deadlock.

private ConcurrentLockSet.Entry

Returns:

the entry for the Lockable, locked for exclusive access
getEntry(Lockable
the Lockable whose entry to return
ref)

Get an entry from the lock table.

public int
getWaitTimeout()

Implements org.apache.derby.impl.services.locks.LockTable.getWaitTimeout.

Get the wait timeout in milliseconds.

public Lock

Returns:

Object that represents the lock.
lockObject(CompatibilitySpace
Compatibility space.
compatibilitySpace, Lockable
Lockable reference.
ref, Object
Qualifier.
qualifier, int
Timeout in milli-seconds
timeout)

Implements org.apache.derby.impl.services.locks.LockTable.lockObject.

Lock an object within a specific compatibility space.

public void
oneLessWaiter()

Implements org.apache.derby.impl.services.locks.LockTable.oneLessWaiter.

Decrease blockCount by one.

public void
oneMoreWaiter()

Implements org.apache.derby.impl.services.locks.LockTable.oneMoreWaiter.

Increase blockCount by one.

public void
setDeadlockTimeout(int
deadlock timeout in milliseconds
timeout)

Implements org.apache.derby.impl.services.locks.LockTable.setDeadlockTimeout.

Set the deadlock timeout.

public void
setDeadlockTrace(boolean
true enables tracing, false disables tracing
val)

Implements org.apache.derby.impl.services.locks.LockTable.setDeadlockTrace.

Enable or disable tracing of deadlocks.

public void
setWaitTimeout(int
wait timeout in milliseconds
timeout)

Implements org.apache.derby.impl.services.locks.LockTable.setWaitTimeout.

Set the wait timeout.

public Map<Lockable, Control>
shallowClone()

Implements org.apache.derby.impl.services.locks.LockTable.shallowClone.

make a shallow clone of myself and my lock controls

private String
toDebugString()

public void
unlock(Latch
the lock to unlock
item, int
the number of times to unlock the item; or zero, meaning take the unlock count from the item
unlockCount)

Implements org.apache.derby.impl.services.locks.LockTable.unlock.

Unlock an object, previously locked by lockObject().

private void
unlock(ConcurrentLockSet.Entry
the entry in which the lock is contained (the current thread must have locked the entry)
entry, Latch
the item to unlock
item, int
the number of times to unlock the item (if zero, take the unlock count from item)
unlockCount)

Unlock an object, previously locked by lockObject().

public Lock

Returns:

the corresponding lock in the group map, or null if the object was not unlocked
unlockReference(CompatibilitySpace
the compatibility space
space, Lockable
a reference to the locked object
ref, Object
qualifier of the lock
qualifier, Map<K, V>
a map representing the locks in a group
group)

Implements org.apache.derby.impl.services.locks.LockTable.unlockReference.

Unlock an object once if it is present in the specified group.

public boolean
zeroDurationLockObject(CompatibilitySpace
the compatibility space
space, Lockable
a reference to the locked object
ref, Object
qualifier of the lock
qualifier, int
maximum time to wait in milliseconds (C_LockFactory.NO_WAIT means don't wait)
timeout)

Implements org.apache.derby.impl.services.locks.LockTable.zeroDurationLockObject.

Lock an object and release the lock immediately.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

blockCountback to summary
private final AtomicInteger blockCount
deadlockTimeoutback to summary
private int deadlockTimeout

Timeout for deadlocks, in ms.
MT - immutable

deadlockTraceback to summary
private boolean deadlockTrace
factoryback to summary
private final AbstractPool factory
locksback to summary
private final ConcurrentHashMap<Lockable, ConcurrentLockSet.Entry> locks

Hash table which maps Lockable objects to Locks.

seenByDeadlockDetectionback to summary
private ArrayList<ConcurrentLockSet.Entry> seenByDeadlockDetection

List containing all entries seen by the last call to addWaiters(). Makes it possible for the deadlock detection thread to lock all the entries it has visited until it has finished. This prevents false deadlocks from being reported (because all observed waiters must still be waiting when the deadlock detection has completed).

waitTimeoutback to summary
private int waitTimeout

Constructor Detail

ConcurrentLockSetback to summary
pack-priv ConcurrentLockSet(AbstractPool factory)

Method Detail

addWaitersback to summary
public void addWaiters(Map<Object, Object> waiters)

Implements org.apache.derby.impl.services.locks.LockTable.addWaiters.

Add all waiters in this lock table to a Map object. This method can only be called by the thread that is currently performing deadlock detection. All entries that are visited in the lock table will be locked when this method returns. The entries that have been seen and locked will be unlocked after the deadlock detection has finished.

Parameters
waiters:Map<Object, Object>

Doc from org.apache.derby.impl.services.locks.LockTable.addWaiters.

the map to add the waiters to

anyoneBlockedback to summary
public boolean anyoneBlocked()

Implements org.apache.derby.impl.services.locks.LockTable.anyoneBlocked.

Check whether anyone is blocked.

Returns:boolean

true if someone is blocked, false otherwise

checkDeadlockback to summary
private Object[] checkDeadlock(ConcurrentLockSet.Entry entry, ActiveLock waitingLock, byte wakeupReason)

Check whether there is a deadlock. Make sure that only one thread enters deadlock detection at a time.

Parameters
entry:ConcurrentLockSet.Entry

the entry in the lock table for the lock request that triggered deadlock detection

waitingLock:ActiveLock

the waiting lock

wakeupReason:byte

the reason for waking up the waiter

Returns:Object[]

an object describing the deadlock

getEntryback to summary
private ConcurrentLockSet.Entry getEntry(Lockable ref)

Get an entry from the lock table. If no entry exists for the Lockable, insert an entry. The returned entry will be locked and is guaranteed to still be present in the table.

Parameters
ref:Lockable

the Lockable whose entry to return

Returns:ConcurrentLockSet.Entry

the entry for the Lockable, locked for exclusive access

getWaitTimeoutback to summary
public int getWaitTimeout()

Implements org.apache.derby.impl.services.locks.LockTable.getWaitTimeout.

Get the wait timeout in milliseconds.

lockObjectback to summary
public Lock lockObject(CompatibilitySpace compatibilitySpace, Lockable ref, Object qualifier, int timeout) throws StandardException

Implements org.apache.derby.impl.services.locks.LockTable.lockObject.

Lock an object within a specific compatibility space.

Parameters
compatibilitySpace:CompatibilitySpace

Compatibility space.

ref:Lockable

Lockable reference.

qualifier:Object

Qualifier.

timeout:int

Timeout in milli-seconds

Returns:Lock

Object that represents the lock.

Exceptions
StandardException:
Standard Derby policy.
oneLessWaiterback to summary
public void oneLessWaiter()

Implements org.apache.derby.impl.services.locks.LockTable.oneLessWaiter.

Decrease blockCount by one.

oneMoreWaiterback to summary
public void oneMoreWaiter()

Implements org.apache.derby.impl.services.locks.LockTable.oneMoreWaiter.

Increase blockCount by one.

setDeadlockTimeoutback to summary
public void setDeadlockTimeout(int timeout)

Implements org.apache.derby.impl.services.locks.LockTable.setDeadlockTimeout.

Set the deadlock timeout.

Parameters
timeout:int

deadlock timeout in milliseconds

setDeadlockTraceback to summary
public void setDeadlockTrace(boolean val)

Implements org.apache.derby.impl.services.locks.LockTable.setDeadlockTrace.

Doc from org.apache.derby.impl.services.locks.LockTable.setDeadlockTrace.

Enable or disable tracing of deadlocks.

Parameters
val:boolean

true enables tracing, false disables tracing

setWaitTimeoutback to summary
public void setWaitTimeout(int timeout)

Implements org.apache.derby.impl.services.locks.LockTable.setWaitTimeout.

Set the wait timeout.

Parameters
timeout:int

wait timeout in milliseconds

shallowCloneback to summary
public Map<Lockable, Control> shallowClone()

Implements org.apache.derby.impl.services.locks.LockTable.shallowClone.

make a shallow clone of myself and my lock controls

Returns:Map<Lockable, Control>

Doc from org.apache.derby.impl.services.locks.LockTable.shallowClone.

a shallow clone of the lock table

toDebugStringback to summary
private String toDebugString()
unlockback to summary
public void unlock(Latch item, int unlockCount)

Implements org.apache.derby.impl.services.locks.LockTable.unlock.

Unlock an object, previously locked by lockObject(). If unlockCOunt is not zero then the lock will be unlocked that many times, otherwise the unlock count is taken from item.

Parameters
item:Latch

Doc from org.apache.derby.impl.services.locks.LockTable.unlock.

the lock to unlock

unlockCount:int

Doc from org.apache.derby.impl.services.locks.LockTable.unlock.

the number of times to unlock the item; or zero, meaning take the unlock count from the item

unlockback to summary
private void unlock(ConcurrentLockSet.Entry entry, Latch item, int unlockCount)

Unlock an object, previously locked by lockObject().

Parameters
entry:ConcurrentLockSet.Entry

the entry in which the lock is contained (the current thread must have locked the entry)

item:Latch

the item to unlock

unlockCount:int

the number of times to unlock the item (if zero, take the unlock count from item)

unlockReferenceback to summary
public Lock unlockReference(CompatibilitySpace space, Lockable ref, Object qualifier, Map<K, V> group)

Implements org.apache.derby.impl.services.locks.LockTable.unlockReference.

Unlock an object once if it is present in the specified group. Also remove the object from the group.

Parameters
space:CompatibilitySpace

the compatibility space

ref:Lockable

a reference to the locked object

qualifier:Object

qualifier of the lock

group:Map<K, V>

a map representing the locks in a group

Returns:Lock

the corresponding lock in the group map, or null if the object was not unlocked

zeroDurationLockObjectback to summary
public boolean zeroDurationLockObject(CompatibilitySpace space, Lockable ref, Object qualifier, int timeout) throws StandardException

Implements org.apache.derby.impl.services.locks.LockTable.zeroDurationLockObject.

Doc from org.apache.derby.impl.services.locks.LockTable.zeroDurationLockObject.

Lock an object and release the lock immediately. Equivalent to 

Lock lock = lockTable.lockObject(space, ref, qualifier, timeout);
lockTable.unlock(lock, 1);
except that the implementation might be more efficient.
Parameters
space:CompatibilitySpace

the compatibility space

ref:Lockable

a reference to the locked object

qualifier:Object

qualifier of the lock

timeout:int

maximum time to wait in milliseconds (C_LockFactory.NO_WAIT means don't wait)

Returns:boolean

true if the object was locked, or false if the object couldn't be locked immediately and timeout was NO_WAIT or LockOwner had the noWait flag set

Exceptions
StandardException:
if the lock could not be obtained
org.apache.derby.impl.services.locks back to summary

private final Class ConcurrentLockSet.Entry

extends Object
Class Inheritance
Class representing an entry in the lock table.

Field Summary

Modifier and TypeField and Description
pack-priv Control
control

The lock control.

private Condition
deadlockDetection

Condition variable which prevents calls to lock() from locking the entry.

private final ReentrantLock
mutex

Mutex used to ensure single-threaded access to the LockControls.

Constructor Summary

AccessConstructor and Description
private
Entry()

Method Summary

Modifier and TypeMethod and Description
pack-priv void
enterDeadlockDetection()

Notify that the lock request that is currently accessing the entry will be entering deadlock detection.

pack-priv void
exitDeadlockDetection()

Notify that the deadlock detection triggered by the current thread has finished.

pack-priv void
lock()

Lock the entry, ensuring exclusive access to the contained Control object.

pack-priv void
lockForDeadlockDetection()

Lock the entry while performing deadlock detection.

pack-priv void
unlock()

Unlock the entry, allowing other threads to lock and access the contained Control object.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

controlback to summary
pack-priv Control control

The lock control.

deadlockDetectionback to summary
private Condition deadlockDetection

Condition variable which prevents calls to lock() from locking the entry. If it is not null, only the thread performing deadlock detection may lock the entry (by calling lockForDeadlockDetection()).

mutexback to summary
private final ReentrantLock mutex

Mutex used to ensure single-threaded access to the LockControls. To avoid Java deadlocks, no thread should ever hold the mutex of more than one entry. Excepted from this requirement is a thread which performs deadlock detection. During deadlock detection, a thread might hold several mutexes, but it is not allowed to hold any mutex when entering the deadlock detection. Only one thread is allowed to perform deadlock detection at a time.

Constructor Detail

Entryback to summary
private Entry()

Method Detail

enterDeadlockDetectionback to summary
pack-priv void enterDeadlockDetection()

Notify that the lock request that is currently accessing the entry will be entering deadlock detection. Unlock the entry to allow the current thread or other threads to lock the entry for deadlock detection, but set the condition variable to prevent regular locking of the entry.

exitDeadlockDetectionback to summary
pack-priv void exitDeadlockDetection()

Notify that the deadlock detection triggered by the current thread has finished. Re-lock the entry and notify any waiters that the deadlock detection has completed.

lockback to summary
pack-priv void lock()

Lock the entry, ensuring exclusive access to the contained Control object. The call will block until the entry can be locked. If the entry is unlocked and deadlockDetection is not null, the entry belongs to a thread which waits for deadlock detection to be initiated, and the call will block until that thread has finished its deadlock detection.

lockForDeadlockDetectionback to summary
pack-priv void lockForDeadlockDetection()

Lock the entry while performing deadlock detection. This method will lock the entry even when deadlockDetection is not null. If deadlockDetection is not null, we know the entry and its Control will not be accessed by others until we have finished the deadlock detection, so it's OK for us to access it.

unlockback to summary
pack-priv void unlock()

Unlock the entry, allowing other threads to lock and access the contained Control object.