Package com.ibm.asyncutil.locks

Interface AsyncStampedLock

All Superinterfaces:

AsyncReadWriteLock

All Known Implementing Classes:

FairAsyncStampedLock

public interface AsyncStampedLock
extends AsyncReadWriteLock

An asynchronously acquirable read-write lock which additionally provides an optimistic read mode. Optimistic read mode can be thought of as a weak reader mode which does not prevent writers from acquiring the lock.

In practice, optimistic reads of brief read-only sections can reduce memory contention. Great care must be taken when reading mutable variables, however, as they can change at any point and knowledge of the underlying accessed structures is necessary to ensure a consistent view of the variables.

Consider the following example. The BitSet class is not inherently thread-safe, so we need a lock to protect it. Further, our hypothetical use case exhibits only rare modifications but extremely frequent queries, which may justify an optimistic read design:

 
 BitSet bits = new BitSet();

 CompletionStage<Boolean> isSet(int idx) {
   // first attempt to optimistically read; if it fails,
   // fall back to full read lock
   final Stamp stamp = this.lock.tryOptimisticRead();

   // lock may already be held, first check the stamp
   if (stamp != null) {

     // BitSet is internally "safe" to concurrent modification during reads
     // i.e. structures cannot be corrupted, but results may be inconsistent
     // for example these individual bits might be separately modified
     final boolean optimistic = this.bits.get(idx) && this.bits.get(idx+1);

     // the read value can only be considered correct if
     // the write lock was not acquired in the interim
     if (stamp.validate()) {
       return StageSupport.completedStage(optimistic);
     }
   }

   // otherwise, if the write lock was already held, or acquired afterwards,
   // acquire the full read lock for a consistent result (fall back from optimism)
   return this.lock.acquireReadLock().thenApply(lockToken -> {
     try {
       return this.bits.get(idx) && this.bits.get(idx+1);
     } finally {
       lockToken.releaseLock();
     }
   }
 }
 
 

This interface draws inspiration from the standard library's StampedLock but certain implementation details may differ. Identical behavior should not be expected from both locking facilities beyond what is explicitly documented.

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

See Also:

AsyncReadWriteLock, StampedLock

Nested Class Summary

Nested Classes

Modifier and Type	Interface	Description
static interface	AsyncStampedLock.Stamp	An object indicating a successful optimistic read attempt.

Nested classes/interfaces inherited from interface com.ibm.asyncutil.locks.AsyncReadWriteLock

AsyncReadWriteLock.ReadLockToken, AsyncReadWriteLock.WriteLockToken

Method Summary

Modifier and Type	Method	Description
static AsyncStampedLock	create()	Creates an AsyncStampedLock
static AsyncStampedLock	createFair()	Creates a fair AsyncStampedLock
AsyncStampedLock.Stamp	tryOptimisticRead()	Attempts to acquire a AsyncStampedLock.Stamp in optimistic-read mode if the lock is not already write-locked.

Methods inherited from interface com.ibm.asyncutil.locks.AsyncReadWriteLock

acquireReadLock, acquireWriteLock, tryReadLock, tryWriteLock

Method Detail

tryOptimisticRead

AsyncStampedLock.Stamp tryOptimisticRead()

Attempts to acquire a AsyncStampedLock.Stamp in optimistic-read mode if the lock is not already write-locked. The stamp may subsequently be validated to check whether the write lock has been acquired

Returns:

a non-null Stamp if the lock is not currently write-locked. Otherwise, returns null

create

static AsyncStampedLock create()

Creates an AsyncStampedLock

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

Returns:

a new AsyncStampedLock

createFair

static AsyncStampedLock createFair()

Creates a fair AsyncStampedLock

Returns:

a new AsyncStampedLock with a fair implementation