Package com.ibm.asyncutil.locks

Interface AsyncNamedReadWriteLock<T>

Type Parameters:

T - the type of named objects used to identify read-write locks

All Known Implementing Classes:

FairAsyncNamedReadWriteLock

public interface AsyncNamedReadWriteLock<T>

A mechanism used to acquire read-write locks shared by a common name. Acquisitions for a given name will share exclusivity with other acquisitions of the same name, based on object equality. Acquisitions of different names may proceed unobstructed.

Implementations will specify whether their lock acquisition is fair or not; this interface does not define this requirement.

Note that implementations will generally employ an underlying Map; as such, the same precautions must be taken regarding mutability of keys (names). Name objects should not change from the time of acquisition to the time of release, with respect to their equality and hash code semantics. The release methods of the returned AsyncReadWriteLock.ReadLockToken and AsyncReadWriteLock.WriteLockToken may throw a ConcurrentModificationException if such a modification is detected.

Method Summary

Modifier and Type	Method	Description
CompletionStage<AsyncReadWriteLock.ReadLockToken>	acquireReadLock(T name)	Acquires the read lock associated with the given name.
CompletionStage<AsyncReadWriteLock.WriteLockToken>	acquireWriteLock(T name)	Exclusively acquires the write lock associated with the given name.
static <T> AsyncNamedReadWriteLock<T>	create()	Creates an AsyncNamedReadWriteLock
static <T> AsyncNamedReadWriteLock<T>	createFair()	Creates a fair AsyncNamedReadWriteLock
Optional<AsyncReadWriteLock.ReadLockToken>	tryReadLock(T name)	Attempts to acquire the read lock associated with the given name.
Optional<AsyncReadWriteLock.WriteLockToken>	tryWriteLock(T name)	Attempts to acquire the write lock associated with the given name.

Method Detail

acquireReadLock

CompletionStage<AsyncReadWriteLock.ReadLockToken> acquireReadLock(T name)

Acquires the read lock associated with the given name. The returned stage will complete when the lock is no longer exclusively held by a writer, and the read lock has been acquired. The stage may already be complete if the write lock for the given name is not currently held.

The AsyncReadWriteLock.ReadLockToken held by the returned stage is used to release the read lock after it has been acquired and the read-lock-protected action has completed.

Parameters:

name - to acquire read access for

Returns:

A CompletionStage which will complete with a AsyncReadWriteLock.ReadLockToken when the read lock associated with name has been acquired

acquireWriteLock

CompletionStage<AsyncReadWriteLock.WriteLockToken> acquireWriteLock(T name)

Exclusively acquires the write lock associated with the given name. The returned stage will complete when the lock is no longer held by any readers or another writer, and the write lock has been exclusively acquired. The stage may already be complete if no locks for the given name are currently held.

The AsyncReadWriteLock.WriteLockToken held by the returned stage is used to release the write lock after it has been acquired and the write-lock-protected action has completed.

Parameters:

name - to acquire exclusive write access for

Returns:

A CompletionStage which will complete with a AsyncReadWriteLock.WriteLockToken when the lock associated with name has been exclusively acquired

tryReadLock

Optional<AsyncReadWriteLock.ReadLockToken> tryReadLock(T name)

Attempts to acquire the read lock associated with the given name. If the associated write lock is not currently held, the returned Optional will hold a ReadLockToken representing this acquisition. Otherwise, the returned Optional will be empty.

The AsyncReadWriteLock.ReadLockToken held by the returned optional is used to release the read lock after it has been acquired and the read-lock-protected action has completed.

Parameters:

name - to acquire read access for

Returns:

An Optional holding a AsyncReadWriteLock.ReadLockToken if the write lock associated with name is not held; otherwise an empty Optional

tryWriteLock

Optional<AsyncReadWriteLock.WriteLockToken> tryWriteLock(T name)

Attempts to acquire the write lock associated with the given name. If the associated write lock or read lock is not currently held, the returned Optional will hold a WriteLockToken representing this acquisition. Otherwise, the returned Optional will be empty.

The AsyncReadWriteLock.WriteLockToken held by the returned optional is used to release the write lock after it has been acquired and the write-lock-protected action has completed.

Parameters:

name - to acquire exclusive write access for

Returns:

An Optional holding a AsyncReadWriteLock.WriteLockToken if the lock associated with name is not held by a writer or any readers; otherwise an empty Optional

create

static <T> AsyncNamedReadWriteLock<T> create()

Creates an AsyncNamedReadWriteLock

The returned lock is only guaranteed to meet the requirements of AsyncNamedReadWriteLock; in particular, no guarantee of fairness is provided.

Returns:

a new AsyncNamedReadWriteLock

createFair

static <T> AsyncNamedReadWriteLock<T> createFair()

Creates a fair AsyncNamedReadWriteLock

Returns:

a new AsyncNamedReadWriteLock with a fair implementation