Package com.ibm.asyncutil.locks

Interface AsyncNamedLock<T>

Type Parameters:

T - the type of named objects used to identify locks

All Known Implementing Classes:

FairAsyncNamedLock

public interface AsyncNamedLock<T>

A mechanism used to acquire mutual exclusion 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.

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 AsyncLock.LockToken may throw a ConcurrentModificationException if such a modification is detected.

Method Summary

Modifier and Type	Method	Description
CompletionStage<AsyncLock.LockToken>	acquireLock(T name)	Acquires the lock associated with the given name.
static <T> AsyncNamedLock<T>	create()	Creates an AsyncNamedLock
static <T> AsyncNamedLock<T>	createFair()	Creates a fair AsyncNamedLock
Optional<AsyncLock.LockToken>	tryLock(T name)	Attempts to immediately acquire the lock associated with the given name, returning a populated Optional if the lock is not currently held.

Method Detail

acquireLock

CompletionStage<AsyncLock.LockToken> acquireLock(T name)

Acquires the lock associated with the given name. The returned stage will complete when the lock is exclusively acquired by this caller. The stage may already be complete if the lock was not held.

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

Parameters:

name - to acquire exclusive access for

Returns:

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

tryLock

Optional<AsyncLock.LockToken> tryLock(T name)

Attempts to immediately acquire the lock associated with the given name, returning a populated Optional if the lock is not currently held.

The AsyncLock.LockToken held by the returned Optional is used to release the lock after it has been acquired and the lock-protected action has completed.

Parameters:

name - to acquire exclusive access for

Returns:

An Optional holding a AsyncLock.LockToken if the lock associated with name is not held; otherwise an empty Optional

create

static <T> AsyncNamedLock<T> create()

Creates an AsyncNamedLock

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

Returns:

a new AsyncNamedLock

createFair

static <T> AsyncNamedLock<T> createFair()

Creates a fair AsyncNamedLock

Returns:

a new AsyncNamedLock with a fair implementation