org.infinispan.util.concurrent.locks
Interface LockManager

All Known Implementing Classes:

DeadlockDetectingLockManager, LockManagerImpl

public interface LockManager

An interface to deal with all aspects of acquiring and releasing locks for cache entries.

Since:

4.0

Author:

Manik Surtani (manik@jboss.org), Mircea.Markus@jboss.com

Method Summary

boolean	acquireLock(InvocationContext ctx, Object key) Attempts to lock an entry if the lock isn't already held in the current scope, and records the lock in the context.
boolean	acquireLock(InvocationContext ctx, Object key, long timeoutMillis)
boolean	acquireLockNoCheck(InvocationContext ctx, Object key) Same as acquireLock(org.infinispan.context.InvocationContext, Object), but doesn't check whether the lock is already acquired by the caller.
int	getLockId(Object key) Returns the 'id' of the lock that will be used to guard access to a given key in the cache.
int	getNumberOfLocksHeld() Retrieves the number of locks currently held.
Object	getOwner(Object key) Retrieves the write lock owner, if any, for the specified cache entry.
boolean	isLocked(Object key) Returns true if the cache entry is locked (either for reading or writing) by anyone, and false otherwise.
boolean	lockAndRecord(Object key, InvocationContext ctx, long timeoutMillis) Acquires a lock of type lockType, on a specific entry in the cache.
boolean	ownsLock(Object key, Object owner) Tests whether a given owner owns a lock of lockType on a particular cache entry.
boolean	possiblyLocked(CacheEntry entry) Inspects the entry for signs that it is possibly locked, and hence would need to be unlocked.
String	printLockInfo() Prints lock information for all locks.
void	unlock(Collection<Object> lockedKeys, Object lockOwner) Releases the lock passed in.
void	unlockAll(InvocationContext ctx) Releases locks present in an invocation context and transaction entry, if one is available.

Method Detail

lockAndRecord

boolean lockAndRecord(Object key,
                      InvocationContext ctx,
                      long timeoutMillis)
                      throws InterruptedException

Acquires a lock of type lockType, on a specific entry in the cache. This method will try for a period of time and give up if it is unable to acquire the required lock. The period of time is specified in Configuration.getLockAcquisitionTimeout().

Parameters:

key - key to lock

ctx - invocation context associated with this invocation

Returns:

true if the lock was acquired, false otherwise.

Throws:

InterruptedException - if interrupted

unlock

void unlock(Collection<Object> lockedKeys,
            Object lockOwner)

Releases the lock passed in.

unlockAll

void unlockAll(InvocationContext ctx)

Releases locks present in an invocation context and transaction entry, if one is available.

Locks are released in reverse order of which they are acquired and registered.

Parameters:

ctx - invocation context to inspect

ownsLock

boolean ownsLock(Object key,
                 Object owner)

Tests whether a given owner owns a lock of lockType on a particular cache entry.

Parameters:

owner - owner

Returns:

true if the owner does own the specified lock type on the specified cache entry, false otherwise.

isLocked

boolean isLocked(Object key)

Returns true if the cache entry is locked (either for reading or writing) by anyone, and false otherwise.

Returns:

true of locked; false if not.

getOwner

Object getOwner(Object key)

Retrieves the write lock owner, if any, for the specified cache entry.

Returns:

the owner of the lock, or null if not locked.

printLockInfo

String printLockInfo()

Prints lock information for all locks.

Returns:

lock information

possiblyLocked

boolean possiblyLocked(CacheEntry entry)

Inspects the entry for signs that it is possibly locked, and hence would need to be unlocked. Note that this is not deterministic, and is pessimistic in that even if an entry is not locked but *might* be locked, this will return true.

As such, this should only be used to determine whether *unlocking* is necessary, not whether locking is necessary. Unlocking an entry that has not been locked has no effect, so this is just an optimisation.

Parameters:

entry - entry to inspect

Returns:

true if the entry *might* be locked, false if the entry definitely is *not* locked.

getNumberOfLocksHeld

int getNumberOfLocksHeld()

Retrieves the number of locks currently held.

Returns:

an integer

getLockId

int getLockId(Object key)

Returns the 'id' of the lock that will be used to guard access to a given key in the cache. Particularly useful if Lock Striping is used and locks may guard more than one key. This mechanism can be used to check whether keys may end up sharing the same lock.

If lock-striping is not used, the identity hash code of the lock created for this specific key is returned. While this may not be of much value, it is done to maintain API compatibility of this method regardless of underlying locking scheme.

Parameters:

key - key to test for

Returns:

the ID of the lock.

acquireLock

boolean acquireLock(InvocationContext ctx,
                    Object key)
                    throws InterruptedException,
                           TimeoutException

Attempts to lock an entry if the lock isn't already held in the current scope, and records the lock in the context.

Parameters:

ctx - context

key - Key to lock

Returns:

true if a lock was needed and acquired, false if it didn't need to acquire the lock (i.e., lock was already held)

Throws:

InterruptedException - if interrupted

TimeoutException - if we are unable to acquire the lock after a specified timeout.

acquireLock

boolean acquireLock(InvocationContext ctx,
                    Object key,
                    long timeoutMillis)
                    throws InterruptedException,
                           TimeoutException

Throws:

InterruptedException

TimeoutException

acquireLockNoCheck

boolean acquireLockNoCheck(InvocationContext ctx,
                           Object key)
                           throws InterruptedException,
                                  TimeoutException

Same as acquireLock(org.infinispan.context.InvocationContext, Object), but doesn't check whether the lock is already acquired by the caller. Useful in the case of transactions that use OwnableReentrantLocks ,as these locks already perform this check internally.

Throws:

InterruptedException

TimeoutException