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:

• Latch.Condition

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 java.lang.Object

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

Field Details

UNLATCHED

public static final int UNLATCHED

See Also:

• Constant Field Values

EXCLUSIVE

public static final int EXCLUSIVE

See Also:

• Constant Field Values

SHARED

public static final int SHARED

See Also:

• Constant Field Values

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