This class is somewhat similar to a single element capacity BlockingQueue and was specifically designed for communicating status between threads. Where a thread needs to let other threads know where it is up to for instance, it can use a BlockingReference to post the state updates that can then be read by the other threads, or waited upon until the state becomes available.

For instance, if we have a thread writing bytes to an InputStream and other threads waiting to read bytes from the corresponding OutputStream once they are written, we use a BlockingReference<Integer> to describe how many bytes have been written and can be safely read. In this case this would be a BlockingReference.newMRSW() for multiple readers.

If I only need to signal between a single producer/consumer thread pair we use BlockingReference.newSRSW().

The expected BlockingQueue like methods are for accessing the item at the head are present:

• take() blocks until available and removes the item
• get() blocks until available and accesses the item without removing it
• peek() does not block and accesses the item if available otherwise returning null.

There are also timeout supporting versions of take() and get().

BlockingReference.java