Class Clutch

java.lang.Object
org.cojen.tupl.util.Latch
org.cojen.tupl.util.Clutch
public abstract class Clutch extends Latch
A clutch is a specialized latch which can support highly concurrent shared requests, under the assumption that exclusive requests are infrequent. When too many shared requests are denied due to high contention, the clutch switches to a special contended mode. Later, when an exclusive clutch is acquired, the mode switches back to non-contended mode. This design allows the clutch to be adaptive, by relying on the exclusive clutch as a signal that access patterns have changed.

Note: Shared access should not be held by any thread indefinitely. If another thread attempts to switch to contended mode, it first needs to acquire exclusive access in order to make the switch. The thread will block even though shared access could have been granted if it just kept trying. This behavior holds true for downgrades as well. Another thread cannot switch to contended mode until after the downgraded latch is fully released.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Clutch.Pack
    Sharable object for supporting contended clutches.

    Nested classes/interfaces inherited from class Latch

    Latch.Condition

  • Field Summary

    Fields inherited from class Latch

    EXCLUSIVE, SHARED, UNLATCHED

  • Constructor Summary

    Constructors
    Constructor
    Description
    Clutch()
     
    Clutch(int initialState)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    final void
    acquireExclusive()
    Acquire the exclusive latch, barging ahead of any waiting threads if possible.
    final void
    acquireExclusiveInterruptibly()
    Acquire the exclusive latch, aborting if interrupted.
    final void
    acquireShared()
    Acquire a shared latch, barging ahead of any waiting threads if possible.
    final void
    acquireSharedInterruptibly()
    Acquire a shared latch, aborting if interrupted.
    final boolean
    acquireSharedUncontended()
    Like tryAcquireShared, except blocks if an exclusive latch is held.
    final int
    acquireSharedUncontendedNanos(long nanosTimeout)
    Like tryAcquireSharedNanos, except blocks if an exclusive latch is held.
    final void
    downgrade(boolean contended)
    Downgrade the held exclusive latch with the option to try switching to contended mode.
    protected abstract Clutch.Pack
    getPack()
    Returns the pack associated with this clutch, which should be shared to reduce the overall memory footprint.
    final boolean
    isContended()
    Returns true if clutch is operating in contended mode.
    static Clutch
    make()
    Return a new Clutch instance, which might share a pack with other instances returned from this method.
    static Clutch
    make(int initialState)
    Return a new Clutch instance, which might share a pack with other instances returned from this method.
    final void
    releaseExclusive(boolean contended)
    Release the held exclusive latch with the option to try switching to contended mode.
    final void
    releaseShared()
    Release a held shared latch.
    String
    toString()
     
    final boolean
    tryAcquireExclusive()
    Try to acquire the exclusive latch, barging ahead of any waiting threads if possible.
    final boolean
    tryAcquireExclusiveNanos(long nanosTimeout)
    Attempt to acquire the exclusive latch, aborting if interrupted.
    final boolean
    tryAcquireShared()
    Try to acquire a shared latch, barging ahead of any waiting threads if possible.
    final boolean
    tryAcquireSharedNanos(long nanosTimeout)
    Attempt to acquire a shared latch, aborting if interrupted.
    final boolean
    tryUpgrade()
    Attempt to upgrade a held shared latch into an exclusive latch.
    final void
    uponExclusive(Runnable cont)
    Invokes the given continuation upon the latch being acquired exclusively.

    Methods inherited from class Latch

    downgrade, hasQueuedThreads, release, releaseEither, releaseExclusive

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • Clutch

      public Clutch()

    • Clutch

      public Clutch(int initialState)
      Parameters:
      initialState - UNLATCHED, EXCLUSIVE, or SHARED

  • Method Details

    • make

      public static Clutch make()
      Return a new Clutch instance, which might share a pack with other instances returned from this method.

    • make

      public static Clutch make(int initialState)
      Return a new Clutch instance, which might share a pack with other instances returned from this method.
      Parameters:
      initialState - UNLATCHED, EXCLUSIVE, or SHARED

    • isContended

      public final boolean isContended()
      Returns true if clutch is operating in contended mode.

    • tryAcquireExclusive

      public final boolean tryAcquireExclusive()
      Description copied from class: Latch
      Try to acquire the exclusive latch, barging ahead of any waiting threads if possible.
      Overrides:
      tryAcquireExclusive in class Latch

    • tryAcquireExclusiveNanos

      public final boolean tryAcquireExclusiveNanos(long nanosTimeout) throws InterruptedException
      Description copied from class: Latch
      Attempt to acquire the exclusive latch, aborting if interrupted.
      Overrides:
      tryAcquireExclusiveNanos in class Latch
      Parameters:
      nanosTimeout - pass negative for infinite timeout
      Throws:
      InterruptedException

    • acquireExclusive

      public final void acquireExclusive()
      Description copied from class: Latch
      Acquire the exclusive latch, barging ahead of any waiting threads if possible.
      Overrides:
      acquireExclusive in class Latch

    • acquireExclusiveInterruptibly

      public final void acquireExclusiveInterruptibly() throws InterruptedException
      Description copied from class: Latch
      Acquire the exclusive latch, aborting if interrupted.
      Overrides:
      acquireExclusiveInterruptibly in class Latch
      Throws:
      InterruptedException

    • uponExclusive

      public final void uponExclusive(Runnable cont)
      Description copied from class: Latch
      Invokes the given continuation upon the latch being acquired exclusively. When acquired, the continuation is run by the current thread, or it's enqueued to be run by a thread which releases the latch. The releasing thread actually retains the latch and runs the continuation, effectively transferring latch ownership. The continuation must not explicitly release the latch, although it can downgrade the latch. Any exception thrown by the continuation is passed to the uncaught exception handler of the running thread, and then the latch is released.
      Overrides:
      uponExclusive in class Latch
      Parameters:
      cont - called with latch held

    • downgrade

      public final void downgrade(boolean contended)
      Downgrade the held exclusive latch with the option to try switching to contended mode. Caller must later call releaseShared instead of releaseExclusive.
      Parameters:
      contended - pass true to try switching to contended mode

    • releaseExclusive

      public final void releaseExclusive(boolean contended)
      Release the held exclusive latch with the option to try switching to contended mode.
      Parameters:
      contended - pass true to try switching to contended mode

    • tryAcquireShared

      public final boolean tryAcquireShared()
      Description copied from class: Latch
      Try to acquire a shared latch, barging ahead of any waiting threads if possible.
      Overrides:
      tryAcquireShared in class Latch

    • tryAcquireSharedNanos

      public final boolean tryAcquireSharedNanos(long nanosTimeout) throws InterruptedException
      Description copied from class: Latch
      Attempt to acquire a shared latch, aborting if interrupted.
      Overrides:
      tryAcquireSharedNanos in class Latch
      Parameters:
      nanosTimeout - pass negative for infinite timeout
      Throws:
      InterruptedException

    • acquireSharedUncontended

      public final boolean acquireSharedUncontended()
      Description copied from class: Latch
      Like tryAcquireShared, except blocks if an exclusive latch is held.
      Overrides:
      acquireSharedUncontended in class Latch
      Returns:
      false if not acquired due to contention with other shared requests

    • acquireSharedUncontendedNanos

      public final int acquireSharedUncontendedNanos(long nanosTimeout) throws InterruptedException
      Description copied from class: Latch
      Like tryAcquireSharedNanos, except blocks if an exclusive latch is held.
      Overrides:
      acquireSharedUncontendedNanos in class Latch
      Parameters:
      nanosTimeout - pass negative for infinite timeout
      Returns:
      -1 if not acquired due to contention with other shared requests, 0 if timed out, or 1 if acquired
      Throws:
      InterruptedException

    • acquireShared

      public final void acquireShared()
      Description copied from class: Latch
      Acquire a shared latch, barging ahead of any waiting threads if possible.
      Overrides:
      acquireShared in class Latch

    • acquireSharedInterruptibly

      public final void acquireSharedInterruptibly() throws InterruptedException
      Description copied from class: Latch
      Acquire a shared latch, aborting if interrupted.
      Overrides:
      acquireSharedInterruptibly in class Latch
      Throws:
      InterruptedException

    • tryUpgrade

      public final boolean tryUpgrade()
      Description copied from class: Latch
      Attempt to upgrade a held shared latch into an exclusive latch. Upgrade fails if shared latch is held by more than one thread. If successful, caller must later call releaseExclusive instead of releaseShared.
      Overrides:
      tryUpgrade in class Latch

    • releaseShared

      public final void releaseShared()
      Description copied from class: Latch
      Release a held shared latch.
      Overrides:
      releaseShared in class Latch

    • toString

      public String toString()
      Overrides:
      toString in class Latch

    • getPack

      protected abstract Clutch.Pack getPack()
      Returns the pack associated with this clutch, which should be shared to reduce the overall memory footprint.