Package com.ibm.asyncutil.locks

Interface AsyncReadWriteLock

All Known Subinterfaces:

AsyncStampedLock

All Known Implementing Classes:

FairAsyncReadWriteLock, FairAsyncStampedLock

public interface AsyncReadWriteLock

An asynchronously acquirable read-write lock.

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

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	AsyncReadWriteLock.ReadLockToken	A lock token indicating that the associated lock has been acquired for reader access.
static interface	AsyncReadWriteLock.WriteLockToken	A lock token indicating that the associated lock has been exclusively acquired for writer access.

Method Summary

Modifier and Type	Method	Description
CompletionStage<AsyncReadWriteLock.ReadLockToken>	acquireReadLock()	Acquires this read lock.
CompletionStage<AsyncReadWriteLock.WriteLockToken>	acquireWriteLock()	Exclusively acquires this write lock.
static AsyncReadWriteLock	create()	Creates an AsyncReadWriteLock
static AsyncReadWriteLock	createFair()	Creates a fair AsyncReadWriteLock
Optional<AsyncReadWriteLock.ReadLockToken>	tryReadLock()	Attempts to immediately acquire the read lock, returning a populated Optional if the lock is not currently held by a writer.
Optional<AsyncReadWriteLock.WriteLockToken>	tryWriteLock()	Attempts to immediately acquire the write lock, returning a populated Optional if the lock is not currently held by a writer or any readers.

Method Detail

acquireReadLock

CompletionStage<AsyncReadWriteLock.ReadLockToken> acquireReadLock()

Acquires this read lock. 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 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.

Returns:

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

tryReadLock

Optional<AsyncReadWriteLock.ReadLockToken> tryReadLock()

Attempts to immediately acquire the read lock, returning a populated Optional if the lock is not currently held by a writer.

Implementations may define whether this attempt can succeed while a writer is waiting to acquire ("barging"). This interface only requires that the attempt will succeed if all writers have released and no new writers are acquiring.

Returns:

An Optional holding a AsyncReadWriteLock.ReadLockToken if the lock is not held by a writer; otherwise an empty Optional

acquireWriteLock

CompletionStage<AsyncReadWriteLock.WriteLockToken> acquireWriteLock()

Exclusively acquires this write lock. 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 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.

Returns:

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

tryWriteLock

Optional<AsyncReadWriteLock.WriteLockToken> tryWriteLock()

Attempts to immediately acquire the write lock, returning a populated Optional if the lock is not currently held by a writer or any readers.

Returns:

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

create

static AsyncReadWriteLock create()

Creates an AsyncReadWriteLock

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

Returns:

a new AsyncReadWriteLock

createFair

static AsyncReadWriteLock createFair()

Creates a fair AsyncReadWriteLock

Returns:

a new AsyncReadWriteLock with a fair implementation