uk.co.strangeskies.flowcontrol

Interface StripedReadWriteLock<K>

Type Parameters:

K - the type of the keys by which locks are indexed

All Superinterfaces:

StripedReadWriteLockRelease<K>

All Known Implementing Classes:

StripedReadWriteLockImpl

public interface StripedReadWriteLock<K>
extends StripedReadWriteLockRelease<K>

A striped lock may contain any number of locks, which are indexed by a keys of a given type.

The purpose of a striped lock is generally to avoid deadlock in systems with many different locks. This is achieved by requiring Threads to acquire all the locks they will need in one go, then releasing them when possible, meaning that a thread will never be waiting for a lock when it already has one.

This class does not enforce that a Thread does not try to obtain more locks when it already has some, this is expected to be dealt with in user code, though it would be trivial to implement a subclass providing this functionality. Instead the StripedReadWriteLockRelease interface is provided such that once locks are acquired, processes can be given the means to release and query the state of those locks without leaking the ability to acquire more.

The overloads of obtainLocks(Collection, Collection) will block until every requested lock is obtained, without allowing deadlocks to occur between multiple blocking threads.

Method Summary

Modifier and Type	Method and Description
void	obtainLocks(java.util.Collection<K> readKeys, java.util.Collection<K> writeKeys) Multiple concurrent calls from different threads do not lock.
void	obtainReadLocks(java.util.Collection<K> readKeys) Multiple concurrent calls from different threads do not lock.
void	obtainWriteLocks(java.util.Collection<K> writeKeys) Multiple concurrent calls from different threads do not lock.
void	wait(K key) Wait for the given lock to become available.
void	wait(K key, long timeoutMilliseconds) Wait for the given lock to become available.
void	wait(K key, long timeoutMilliseconds, int timeoutNanoseconds) Wait for the given lock to become available.

Methods inherited from interface uk.co.strangeskies.flowcontrol.StripedReadWriteLockRelease

downgradeLock, isLockHeldByCurrentThread, isReadLockHeldByCurrentThread, isWriteLockHeldByCurrentThread, readLocksHeldByCurrentThread, releaseLock, releaseLocks, releaseLocks, releaseReadLock, releaseReadLocks, releaseWriteLock, releaseWriteLocks, writeLocksHeldByCurrentThread

Method Detail

obtainLocks

void obtainLocks(java.util.Collection<K> readKeys,
                 java.util.Collection<K> writeKeys)
          throws java.lang.InterruptedException

Multiple concurrent calls from different threads do not lock. Blocks until all locks can be obtained (or until interruption).

Parameters:

readKeys - Keys for read locks to be obtained

writeKeys - Keys for write locks to be obtained

Throws:

java.lang.InterruptedException - The obtaining thread was interrupted before the locks could be obtained.

obtainReadLocks

void obtainReadLocks(java.util.Collection<K> readKeys)
              throws java.lang.InterruptedException

Multiple concurrent calls from different threads do not lock. Blocks until all locks can be obtained (or until interruption).

Parameters:

readKeys - Keys for read locks to be obtained

Throws:

java.lang.InterruptedException - The obtaining thread was interrupted before the locks could be obtained.

obtainWriteLocks

void obtainWriteLocks(java.util.Collection<K> writeKeys)
               throws java.lang.InterruptedException

Multiple concurrent calls from different threads do not lock. Blocks until all locks can be obtained (or until interruption).

Parameters:

writeKeys - Keys for write locks to be obtained

Throws:

java.lang.InterruptedException - The obtaining thread was interrupted before the locks could be obtained.

wait

void wait(K key)
   throws java.lang.InterruptedException

Wait for the given lock to become available.

Parameters:

key - The key to the lock on which we wish to wait.

Throws:

java.lang.InterruptedException - The waiting thread was interrupted before the lock could be obtained.

wait

void wait(K key,
          long timeoutMilliseconds)
   throws java.lang.InterruptedException

Wait for the given lock to become available.

Parameters:

key - The key to the lock on which we wish to wait.

timeoutMilliseconds - The timeout in milliseconds to wait.

Throws:

java.lang.InterruptedException - The waiting thread was interrupted before the lock could be obtained.

wait

void wait(K key,
          long timeoutMilliseconds,
          int timeoutNanoseconds)
   throws java.lang.InterruptedException

Wait for the given lock to become available.

Parameters:

key - The key to the lock on which we wish to wait.

timeoutMilliseconds - The timeout component in milliseconds to wait.

timeoutNanoseconds - The timeout component in nanoseconds to wait.

Throws:

java.lang.InterruptedException - The waiting thread was interrupted before the lock could be obtained.