Class Latch

java.lang.Object
org.cojen.tupl.util.Latch
Direct Known Subclasses:
Clutch, Clutch.Pack
public class Latch extends Object
Non-reentrant read-write latch, designed for throughput over fairness. Implementation doesn't track thread ownership or check for illegal usage. As a result, it typically outperforms ReentrantLock and built-in Java synchronization. Although latch acquisition is typically unfair, waiting threads aren't starved indefinitely.
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    Latch.Condition
    Manages a queue of waiting threads, associated with a Latch instance.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    EXCLUSIVE
     
    static final int
    SHARED
     
    static final int
    UNLATCHED
     

  • Constructor Summary

    Constructors
    Constructor
    Description
    Latch()
     
    Latch(int initialState)
     

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    acquireExclusive()
    Acquire the exclusive latch, barging ahead of any waiting threads if possible.
    void
    acquireExclusiveInterruptibly()
    Acquire the exclusive latch, aborting if interrupted.
    void
    acquireShared()
    Acquire a shared latch, barging ahead of any waiting threads if possible.
    void
    acquireSharedInterruptibly()
    Acquire a shared latch, aborting if interrupted.
    boolean
    acquireSharedUncontended()
    Like tryAcquireShared, except blocks if an exclusive latch is held.
    int
    acquireSharedUncontendedNanos(long nanosTimeout)
    Like tryAcquireSharedNanos, except blocks if an exclusive latch is held.
    final void
    downgrade()
    Downgrade the held exclusive latch into a shared latch.
    final boolean
    hasQueuedThreads()
     
    final void
    release(boolean exclusive)
    Convenience method, which releases the held exclusive or shared latch.
    final void
    releaseEither()
    Releases an exclusive or shared latch.
    final void
    releaseExclusive()
    Release the held exclusive latch.
    void
    releaseShared()
    Release a held shared latch.
    String
    toString()
     
    boolean
    tryAcquireExclusive()
    Try to acquire the exclusive latch, barging ahead of any waiting threads if possible.
    boolean
    tryAcquireExclusiveNanos(long nanosTimeout)
    Attempt to acquire the exclusive latch, aborting if interrupted.
    boolean
    tryAcquireShared()
    Try to acquire a shared latch, barging ahead of any waiting threads if possible.
    boolean
    tryAcquireSharedNanos(long nanosTimeout)
    Attempt to acquire a shared latch, aborting if interrupted.
    boolean
    tryUpgrade()
    Attempt to upgrade a held shared latch into an exclusive latch.
    void
    uponExclusive(Runnable cont)
    Invokes the given continuation upon the latch being acquired exclusively.

    Methods inherited from class Object

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

  • Field Details

  • Constructor Details

    • Latch

      public Latch()

    • Latch

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

  • Method Details

    • tryAcquireExclusive

      public boolean tryAcquireExclusive()
      Try to acquire the exclusive latch, barging ahead of any waiting threads if possible.

    • tryAcquireExclusiveNanos

      public boolean tryAcquireExclusiveNanos(long nanosTimeout) throws InterruptedException
      Attempt to acquire the exclusive latch, aborting if interrupted.
      Parameters:
      nanosTimeout - pass negative for infinite timeout
      Throws:
      InterruptedException

    • acquireExclusive

      public void acquireExclusive()
      Acquire the exclusive latch, barging ahead of any waiting threads if possible.

    • acquireExclusiveInterruptibly

      public void acquireExclusiveInterruptibly() throws InterruptedException
      Acquire the exclusive latch, aborting if interrupted.
      Throws:
      InterruptedException

    • uponExclusive

      public void uponExclusive(Runnable cont)
      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.
      Parameters:
      cont - called with latch held

    • downgrade

      public final void downgrade()
      Downgrade the held exclusive latch into a shared latch. Caller must later call releaseShared instead of releaseExclusive.

    • releaseExclusive

      public final void releaseExclusive()
      Release the held exclusive latch.

    • release

      public final void release(boolean exclusive)
      Convenience method, which releases the held exclusive or shared latch.
      Parameters:
      exclusive - call releaseExclusive if true, else call releaseShared

    • releaseEither

      public final void releaseEither()
      Releases an exclusive or shared latch.

    • tryAcquireShared

      public boolean tryAcquireShared()
      Try to acquire a shared latch, barging ahead of any waiting threads if possible.

    • tryAcquireSharedNanos

      public boolean tryAcquireSharedNanos(long nanosTimeout) throws InterruptedException
      Attempt to acquire a shared latch, aborting if interrupted.
      Parameters:
      nanosTimeout - pass negative for infinite timeout
      Throws:
      InterruptedException

    • acquireSharedUncontended

      public boolean acquireSharedUncontended()
      Like tryAcquireShared, except blocks if an exclusive latch is held.
      Returns:
      false if not acquired due to contention with other shared requests

    • acquireSharedUncontendedNanos

      public int acquireSharedUncontendedNanos(long nanosTimeout) throws InterruptedException
      Like tryAcquireSharedNanos, except blocks if an exclusive latch is held.
      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 void acquireShared()
      Acquire a shared latch, barging ahead of any waiting threads if possible.

    • acquireSharedInterruptibly

      public void acquireSharedInterruptibly() throws InterruptedException
      Acquire a shared latch, aborting if interrupted.
      Throws:
      InterruptedException

    • tryUpgrade

      public boolean tryUpgrade()
      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.

    • releaseShared

      public void releaseShared()
      Release a held shared latch.

    • hasQueuedThreads

      public final boolean hasQueuedThreads()

    • toString

      public String toString()
      Overrides:
      toString in class Object