com.sun.sgs.impl.util.lock
Class LockManager<K>

java.lang.Object
  com.sun.sgs.impl.util.lock.LockManager<K>

Type Parameters:

K - the type of key

Direct Known Subclasses:

MultiLockManager, TxnLockManager

public class LockManager<K>
extends Object

A class for managing lock conflicts.

This class uses the Logger named com.sun.sgs.impl.util.lock to log information at the following logging levels:

• FINER - Releasing locks; requesting, waiting for, and returning from lock requests
• FINEST - Notifying new lock owners, results of requesting locks before waiting, releasing locks, results of attempting to assign locks to waiters

The implementation of this class uses the following thread synchronization scheme to avoid internal deadlocks:

• Synchronization is only used on Locker objects and on the Maps that hold Lock objects
• A thread can synchronize on at most one locker and one lock at a time, always synchronizing on the locker first

To make it easier to adhere to these rules, the implementation takes the following steps:

• The Lock class is not synchronized

  Callers of non-Object methods on the Lock class should make sure that they are synchronized on the associated key map.

• The Locker class and its subclasses only use synchronization for getter and setter methods
• Blocks synchronized on a Lock should not synchronize on anything else

  The implementation enforces this requirement by having lock methods not make calls to other classes, and by performing minimal work while synchronized on the associated key map.

• Blocks synchronized on a Locker should not synchronize on a different locker, but can synchronize on a Lock In fact, only one method synchronizes on a Locker and on a Lock -- the waitForLockInternal method. That method also makes sure that the only synchronized Locker methods that it calls are on the locker it has already synchronized on.
• Uses assertions to check adherence to the scheme

Field Summary

(package private) ThreadLocal<K>	currentKeySync When assertions are enabled, hold the Key whose associated Map the current thread is synchronized on, if any.
(package private) ThreadLocal<Locker<K>>	currentLockerSync When assertions are enabled, holds the Locker that the current thread is synchronized on, if any.
(package private) static LoggerWrapper	logger The logger for this class.

Constructor Summary

LockManager(long lockTimeout, int numKeyMaps)
Creates an instance of this class.

Method Summary

(package private) Map<K,Lock<K>>	getKeyMap(K key) Returns the key map to use for the specified key.
(package private) Lock<K>	getLock(K key, Map<K,Lock<K>> keyMap) Returns the lock associated with the specified key from the key map, which should be the one returned by calling getKeyMap.
List<LockRequest<K>>	getOwners(K key) Returns a possibly read-only list that contains a snapshot of the current owners of a lock, as identified by lock requests.
List<LockRequest<K>>	getWaiters(K key) Returns a possibly read-only list that contains a snapshot of the current waiters for a lock, as identified by lock requests.
LockConflict<K>	lock(Locker<K> locker, K key, boolean forWrite) Attempts to acquire a lock, waiting if needed.
LockConflict<K>	lockNoWait(Locker<K> locker, K key, boolean forWrite) Attempts to acquire a lock, returning immediately.
(package private) LockConflict<K>	lockNoWaitInternal(Locker<K> locker, K key, boolean forWrite) Attempts to acquire a lock, returning immediately.
void	releaseLock(Locker<K> locker, K key) Releases a lock held by a locker.
(package private) void	releaseLockInternal(Locker<K> locker, K key, boolean downgrade) Releases a lock, but only downgrading it if downgrade is true.
LockConflict<K>	waitForLock(Locker<K> locker) Waits for a previous attempt to obtain a lock that blocked.
(package private) LockConflict<K>	waitForLockInternal(Locker<K> locker) Waits for a previous attempt to obtain a lock that blocked.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

logger

static final LoggerWrapper logger

The logger for this class.

currentLockerSync

final ThreadLocal<Locker<K>> currentLockerSync

When assertions are enabled, holds the Locker that the current thread is synchronized on, if any.

currentKeySync

final ThreadLocal<K> currentKeySync

When assertions are enabled, hold the Key whose associated Map the current thread is synchronized on, if any.

Constructor Detail

LockManager

public LockManager(long lockTimeout,
                   int numKeyMaps)

Creates an instance of this class.

Parameters:

lockTimeout - the maximum number of milliseconds to acquire a lock

numKeyMaps - the number of separate maps to use for storing keys

Throws:

IllegalArgumentException - if lockTimeout or numKeyMaps is less than 1

Method Detail

lock

public LockConflict<K> lock(Locker<K> locker,
                            K key,
                            boolean forWrite)

Attempts to acquire a lock, waiting if needed. Returns information about conflicts that occurred while attempting to acquire the lock that prevented the lock from being acquired, or else null if the lock was acquired. If the type field of the return value is DEADLOCK, then the caller should abort the transaction, and any subsequent lock or wait requests will throw IllegalStateException. Otherwise, the caller can repeat this call, and any conflicts from earlier calls will be ignored.

Parameters:

locker - the locker requesting the lock

key - the key identifying the lock

forWrite - whether to request a write lock

Returns:

lock conflict information, or null if there was no conflict

Throws:

IllegalArgumentException - if locker has a different lock manager

IllegalStateException - if an earlier lock attempt for this transaction produced a deadlock, or if still waiting for an earlier attempt to complete

lockNoWait

public LockConflict<K> lockNoWait(Locker<K> locker,
                                  K key,
                                  boolean forWrite)

Attempts to acquire a lock, returning immediately. Returns information about any conflict that occurred while attempting to acquire the lock, or else null if the lock was acquired. If the attempt to acquire the lock was blocked, returns a value with a type field of BLOCKED rather than waiting. If the type field of the return value is DEADLOCK, then the caller should abort the transaction, and any subsequent lock or wait requests will throw IllegalStateException. Otherwise, the caller can repeat this call, and any conflicts from earlier calls will be ignored.

Parameters:

locker - the locker requesting the lock

key - the key identifying the lock

forWrite - whether to request a write lock

Returns:

lock conflict information, or null if there was no conflict

Throws:

IllegalArgumentException - if locker has a different lock manager

IllegalStateException - if an earlier lock attempt for this transaction produced a deadlock, or if still waiting for an earlier attempt to complete

waitForLock

public LockConflict<K> waitForLock(Locker<K> locker)

Waits for a previous attempt to obtain a lock that blocked. Returns information about any conflict that occurred while attempting to acquire the lock, or else null if the lock was acquired or the transaction was not waiting. If the type field of the return value is DEADLOCK, then the caller should abort the transaction, and any subsequent lock or wait requests will throw IllegalStateException.

Parameters:

locker - the locker requesting the lock

Returns:

lock conflict information, or null if there was no conflict

Throws:

IllegalArgumentException - if locker has a different lock manager

releaseLock

public void releaseLock(Locker<K> locker,
                        K key)

Releases a lock held by a locker. This method does nothing if the lock is not held.

Parameters:

locker - the locker holding the lock

key - the key identifying the lock

Throws:

IllegalArgumentException - if locker has a different lock manager

getOwners

public List<LockRequest<K>> getOwners(K key)

Returns a possibly read-only list that contains a snapshot of the current owners of a lock, as identified by lock requests.

Parameters:

key - the key identifying the lock

Returns:

a list of the requests

getWaiters

public List<LockRequest<K>> getWaiters(K key)

Returns a possibly read-only list that contains a snapshot of the current waiters for a lock, as identified by lock requests.

Parameters:

key - the key identifying the lock

Returns:

a list of the requests

getKeyMap

Map<K,Lock<K>> getKeyMap(K key)

Returns the key map to use for the specified key.

Parameters:

key - the key

Returns:

the associated key map

getLock

Lock<K> getLock(K key,
                Map<K,Lock<K>> keyMap)

Returns the lock associated with the specified key from the key map, which should be the one returned by calling getKeyMap. The lock on keyMap should be held.

Parameters:

key - the key

keyMap - the keyMap

Returns:

the associated lock

lockNoWaitInternal

LockConflict<K> lockNoWaitInternal(Locker<K> locker,
                                   K key,
                                   boolean forWrite)

Attempts to acquire a lock, returning immediately. Like lockNoWait(com.sun.sgs.impl.util.lock.Locker, K, boolean), but does not check that the correct lock manager was supplied.

Parameters:

locker - the locker requesting the lock

key - the key identifying the lock

forWrite - whether to request a write lock

Returns:

lock conflict information, or null if there was no conflict

Throws:

IllegalStateException - if an earlier lock attempt for this transaction produced a deadlock, or if still waiting for an earlier attempt to complete

waitForLockInternal

LockConflict<K> waitForLockInternal(Locker<K> locker)

Waits for a previous attempt to obtain a lock that blocked. Like waitForLock(com.sun.sgs.impl.util.lock.Locker), but does not check that the correct lock manager was supplied.

Parameters:

locker - the locker requesting the lock

Returns:

lock conflict information, or null if there was no conflict

releaseLockInternal

void releaseLockInternal(Locker<K> locker,
                         K key,
                         boolean downgrade)

Releases a lock, but only downgrading it if downgrade is true. Like releaseLock(com.sun.sgs.impl.util.lock.Locker, K), but permits specifying if the lock is being downgraded rather than fully released.

Parameters:

locker - the locker holding the lock

key - the key identifying the lock

downgrade - whether the lock should only be downgraded

Throws:

IllegalArgumentException - if locker has a different lock manager