io.atlassian.util.concurrent

Class BlockingReference<V>

java.lang.Object

io.atlassian.util.concurrent.BlockingReference<V>

Type Parameters:

V - the value type

@ThreadSafe
public class BlockingReference<V>
extends Object

A Reference with queue semantics where the current reference may be retrieved or taken instead, and if there is no current element then it will be block until the reference becomes available. This is somewhat 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 or MRSW usage. Multiple writers will overwrite each other's elements and the chosen value will be arbitrary in the absence of any external consensus. If multiple readers are waiting to take() a value, one reader will be arbitrarily chosen (similar to Condition.signal()). Multiple readers can however get() the current value if it is not null, but they may see the current value more than once. If multiple readers attempt to get() a value from the SRSW reference and it is not yet present then only one waiting thread may be notified, please use the MRSW version for this case.

This implementation has been optimized for SRSW performance with set(Object)/take() pairs.

This class is explicit in that it handles take/get separately.

See Also:

BlockingQueue

Constructor Summary

Constructors

Constructor and Description
BlockingReference() Deprecated. use newSRSW() instead.
BlockingReference(V value) Deprecated. use newSRSW() instead.

Method Summary

Modifier and Type	Method and Description
void	clear() Clear the current reference.
V	get() Gets the current element if it is not null, if it is null then this method blocks and waits until it is not null.
V	get(long time, TimeUnit unit) Gets the current element if it is not null, if it is null then this method blocks and waits until it is not null.
boolean	isEmpty() Whether or not the current value is null or not.
static <V> BlockingReference<V>	newMRSW() Create a BlockingReference best suited to multi-reader/single-writer situations.
static <V> BlockingReference<V>	newMRSW(V initialValue) Create a BlockingReference best suited to multi-reader/single-writer situations.
static <V> BlockingReference<V>	newSRSW() Create a BlockingReference best suited to single-reader/single-writer situations.
static <V> BlockingReference<V>	newSRSW(V initialValue) Create a BlockingReference best suited to single-reader/single-writer situations.
V	peek() Return the current value whether 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 time, 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

@Deprecated
public BlockingReference()

Deprecated. use newSRSW() instead.

Creates a new SRSW BlockingReference.

BlockingReference

@Deprecated
public BlockingReference(@NotNull
                                     V value)

Deprecated. use newSRSW() instead.

Creates a new SRSW BlockingReference.

Parameters:

value - a V object.

Method Detail

newSRSW

public static <V> BlockingReference<V> newSRSW()

Create a BlockingReference best suited to single-reader/single-writer situations. In a MRSW case this instance may get missed signals if multiple reader threads are all waiting on the value.

Returns:

a BlockingReference object.

newSRSW

public static <V> BlockingReference<V> newSRSW(V initialValue)

Create a BlockingReference best suited to single-reader/single-writer situations. In a MRSW case this instance may get missed signals if multiple reader threads are all waiting on the value.

Type Parameters:

V - a V value to reference.

Parameters:

initialValue - the initial value

Returns:

a BlockingReference.

newMRSW

public static <V> BlockingReference<V> newMRSW()

Create a BlockingReference best suited to multi-reader/single-writer situations. In a SRSW case this instance may not perform quite as well.

Returns:

a BlockingReference.

newMRSW

public static <V> BlockingReference<V> newMRSW(V initialValue)

Create a BlockingReference best suited to multi-reader/single-writer situations. In a SRSW case this instance may not perform quite as well.

Type Parameters:

V - a V value to reference.

Parameters:

initialValue - the initial value

Returns:

a BlockingReference.

take

@NotNull
public final V take()
                      throws 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:

InterruptedException - if the current thread is interrupted while waiting

take

@NotNull
public final V take(long time,
                             TimeUnit unit)
                      throws TimeoutException,
                             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:

time - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

the current element

Throws:

InterruptedException - if the current thread is interrupted while waiting

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

get

@NotNull
public final V get()
                     throws InterruptedException

Gets the current element if it is not null, if it is null then this method blocks and waits until it is not null. Unlike take() it does not reset the current element to 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:

InterruptedException - if the current thread is interrupted while waiting

get

@NotNull
public final V get(long time,
                            @NotNull
                            TimeUnit unit)
                     throws TimeoutException,
                            InterruptedException

Gets the current element if it is not null, if it is null then this method blocks and waits until it is not null. Unlike take() it does not reset the current element to 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.

Parameters:

time - a long.

unit - a TimeUnit.

Returns:

the current element

Throws:

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

InterruptedException - if the current thread is interrupted while waiting

set

public final void set(@NotNull
                      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 final 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.

peek

@Nullable
public final V peek()

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

Returns:

the current reference or null if there is none.

clear

public final void clear()

Clear the current reference.