com.atlassian.util.concurrent
Class BlockingReference<V>

java.lang.Object
  com.atlassian.util.concurrent.BlockingReference<V>

Type Parameters:

V - the value type

@ThreadSafe
public class BlockingReference<V>
extends java.lang.Object

A Reference with queue semantics where rather than getting the current reference it is taken instead. Analogous to a single element BlockingQueue.

Note: this class does not support null elements being set(Object) and will throw an exception. If the internal reference is null, then calls to take() or take(long, TimeUnit) will block.

This class is most suited to SRSW usage. Multiple writers will overwrite each other's elements, and if multiple readers are waiting to take a value, one reader will be arbitrarily chosen (similar to Condition.signal()).

See Also:

BlockingQueue

Constructor Summary

BlockingReference()

Method Summary

boolean	isEmpty() Whether or not the current value is null or not.
void	set(V value) Set the value of this reference.
V	take() Takes the current element if it is not null and replaces it with null.
V	take(long timeout, java.util.concurrent.TimeUnit unit) Takes the current element if it is not null and replaces it with null.

Methods inherited from class java.lang.Object

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

Constructor Detail

BlockingReference

public BlockingReference()

Method Detail

take

public V take()
       throws java.lang.InterruptedException

Takes the current element if it is not null and replaces it with null. If the current element is null then wait until it becomes non-null.

If the current thread:

• has its interrupted status set on entry to this method; or
• is interrupted while waiting,

then InterruptedException is thrown and the current thread's interrupted status is cleared.

Returns:

the current element

Throws:

java.lang.InterruptedException - if the current thread is interrupted while waiting

take

public V take(long timeout,
              java.util.concurrent.TimeUnit unit)
       throws java.util.concurrent.TimeoutException,
              java.lang.InterruptedException

Takes the current element if it is not null and replaces it with null. If the current element is null then wait until it becomes non-null. The method will throw a TimeoutException if the timeout is reached before an element becomes available.

If the current thread:

• has its interrupted status set on entry to this method; or
• is interrupted while waiting,

then InterruptedException is thrown and the current thread's interrupted status is cleared.

Parameters:

timeout - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

the current element

Throws:

java.lang.InterruptedException - if the current thread is interrupted while waiting

java.util.concurrent.TimeoutException - if the timeout is reached without another thread having called set(Object).

set

public void set(V value)

Set the value of this reference. This method is lock-free. A thread waiting in take() or take(long, TimeUnit) will be released and given this value.

Parameters:

value - the new value.

isEmpty

public boolean isEmpty()

Whether or not the current value is null or not. If this is true and the next call to take() or take(long, TimeUnit) will not block.

Returns:

true if the current reference is null.