com.bigdata.util.concurrent

Class Latch

java.lang.Object

com.bigdata.util.concurrent.Latch

Direct Known Subclasses:

KVOLatch

public class Latch
extends Object

A synchronization aid that allows one or more threads to await a counter becoming zero. Once the counter reaches zero, all waiting threads are released. Threads may invoke await() any time after the counter has been incremented. They will not be released until the counter is zero. The typical pattern is to incrementing the counter before some operation and the decrement the counter after that operation. This pattern may be safely used in combination with nested invocations and with concurrent threads.

Note: This class is very similar to a CountDownLatch, however the counter maximum is not specified in advance.

Version:

$Id$

Author:

Bryan Thompson

Field Summary

Fields

Modifier and Type	Field and Description
protected static org.apache.log4j.Logger	log

Constructor Summary

Constructors

Constructor and Description
Latch()
Latch(ReentrantLock lock)
Latch(String name, ReentrantLock lock)

Method Summary

Methods

Modifier and Type	Method and Description
long	addAndGet(long delta) Adds the delta to the internal counter.
void	await() Await the counter to become zero unless interrupted.
boolean	await(long timeout, TimeUnit unit) Await the counter to become zero, but no longer than the timeout.
long	dec() Decrements the internal counter and releases the blocked thread(s) if the counter reaches zero.
long	get() The counter value (peek at current value without obtaining the lock).
long	inc() Increments the internal counter.
protected void	signal() Invoked when the latch reaches zero after any threads blocked at await(long, TimeUnit) have been released.
String	toString()

Methods inherited from class java.lang.Object

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

Field Detail

log

protected static final transient org.apache.log4j.Logger log

Constructor Detail

Latch

public Latch()

Latch

public Latch(ReentrantLock lock)

Parameters:

lock - The lock to be used (optional). When none is specified, a new lock will be allocated. The caller MAY choose to specify the lock in order to avoid nested lock designs by using the same lock inside the Latch and in some outer context.

Latch

public Latch(String name,
     ReentrantLock lock)

Parameters:

name - An optional name that will be displayed by toString() along with the current counter value.

lock - The lock to be used (optional). When none is specified, a new lock will be allocated. The caller MAY choose to specify the lock in order to avoid nested lock designs by using the same lock inside the Latch and in some outer context.

Method Detail

toString

public String toString()

Overrides:

toString in class Object

get

public long get()

The counter value (peek at current value without obtaining the lock).

inc

public long inc()

Increments the internal counter.

Returns:

The post-increment value of the counter.

addAndGet

public long addAndGet(long delta)

Adds the delta to the internal counter.

Returns:

The post-increment value of the counter.

dec

public long dec()

Decrements the internal counter and releases the blocked thread(s) if the counter reaches zero.

Returns:

The post-decrement value.

Throws:

IllegalStateException - if the counter would become negative.

signal

protected void signal()
               throws InterruptedException

Invoked when the latch reaches zero after any threads blocked at await(long, TimeUnit) have been released. This may be overridden to perform additional processing, such as moving an associated object onto another queue.

CAUTION: DO NOT invoke any operation from within this method which could block as that would cause the thread running the asynchronous write task in which this method is invoked to block. If you are transferring objects to a queue, the queue MUST be unbounded.

Throws:

InterruptedException

await

public void await()
           throws InterruptedException

Await the counter to become zero unless interrupted.

Throws:

InterruptedException

await

public boolean await(long timeout,
            TimeUnit unit)
              throws InterruptedException

Await the counter to become zero, but no longer than the timeout.

Parameters:

timeout - The timeout.

unit - The unit in which the timeout is expressed.

Returns:

true if the counter reached zero and false if the timeout was exceeded before the counter reached zero.

Throws:

InterruptedException