Class FairBlockingQueue<E>

java.lang.Object

org.apache.tomcat.jdbc.pool.FairBlockingQueue<E>

Type Parameters:

E - Type of element in the queue

All Implemented Interfaces:

Iterable<E>, Collection<E>, BlockingQueue<E>, Queue<E>

public class FairBlockingQueue<E>
extends Object
implements BlockingQueue<E>

A simple implementation of a blocking queue with fairness waiting. Waiters of method poll(...) are handed items in the order in which they registered as waiters. Locking is fine grained: a shared lock is only used during the first level of contention, while waiting is done on a per-waiter CountDownLatch, so order is guaranteed once a thread has registered itself as a waiter - a caller that has not registered yet may still barge ahead when it races for the shared lock.
Not all of the methods of the BlockingQueue are supported: the ones that are not throw UnsupportedOperationException.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
protected class	FairBlockingQueue.ExchangeCountDownLatch<T>	A count down latch that can be used to exchange information.
protected class	FairBlockingQueue.FairIterator	Iterator safe from concurrent modification exceptions.
protected class	FairBlockingQueue.ItemFuture<T>	A future used to check if a connection has been made available.

Constructor Summary

Constructors

Constructor	Description
FairBlockingQueue()	Creates a new fair blocking queue.

Method Summary

Modifier and Type	Method	Description
boolean	add(E e)
boolean	addAll(Collection<? extends E> c)
void	cancelWaiters()	Fail all the polls that are waiting for an item on this queue.
void	clear()
boolean	contains(Object e)
boolean	containsAll(Collection<?> c)
int	drainTo(Collection<? super E> c)
int	drainTo(Collection<? super E> c, int maxElements)
E	element()
boolean	hasRegisteredWaiter()	Reports whether any caller is registered on this queue waiting for an item - through a timed poll or an asynchronous one.
boolean	isEmpty()
Iterator<E>	iterator()
boolean	offer(E e)	Will always return true, queue is unbounded.
boolean	offer(E e, long timeout, TimeUnit unit)	Will never time out, as it invokes the offer(Object) method: the element is always inserted, so the timeout is never applied and, despite the declaration, InterruptedException is never thrown.
E	peek()
E	poll()
E	poll(long timeout, TimeUnit unit)	Fair retrieval of an object in the queue.
Future<E>	pollAsync()	Request an item from the queue asynchronously.
void	put(E e)
int	remainingCapacity()
E	remove()
boolean	remove(Object e)
boolean	removeAll(Collection<?> c)
boolean	retainAll(Collection<?> c)
int	size()
E	take()	Delegates to poll(long, TimeUnit) with an effectively unbounded timeout, so the wait also ends the way that method documents for a queue whose waiters cancelWaiters() has failed.
Object[]	toArray()
<T> T[]	toArray(T[] a)

Methods inherited from class Object

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

Methods inherited from interface Collection

equals, hashCode, parallelStream, removeIf, spliterator, stream, toArray

Methods inherited from interface Iterable

forEach

Constructor Details

FairBlockingQueue

public FairBlockingQueue()

Creates a new fair blocking queue.

Method Details

offer

public boolean offer(E e)

Will always return true, queue is unbounded.

Specified by:

offer in interface BlockingQueue<E>

Specified by:

offer in interface Queue<E>

Throws:

NullPointerException - - if the specified element is null

poll

public E poll(long timeout,
 TimeUnit unit)
       throws InterruptedException

Fair retrieval of an object in the queue. Objects are returned in the order the threads requested them. If the wait is interrupted but an object was handed over to this waiter all the same, the object is returned and the interrupt status of the calling thread is restored instead of being cleared. On a queue whose waiters the cancelWaiters() method has failed, an empty queue hands back no item right away instead of parking the caller: such a queue is never fed again, so waiting could only end in the same empty-handed return.

Specified by:

poll in interface BlockingQueue<E>

Throws:

InterruptedException

pollAsync

public Future<E> pollAsync()

Request an item from the queue asynchronously. If no item is available, the returned future registers a waiter on the queue. Cancelling the future deregisters that waiter again, provided the item has not already been handed over to the future. A future that is no longer needed must therefore be cancelled, so that a subsequent offer does not hand an item over to a future nobody is waiting on. A Future.get(long, TimeUnit) call on the future that times out deregisters the waiter in the same way and fails the future terminally, so that every later retrieval from it fails right away instead of waiting for an item that can no longer be handed over. Once cancelWaiters() has been called, no waiter is registered anymore: the returned future is cancelled right away, as the caller that cancelled the waiters offers no further item that could serve it.

Returns:

- a future pending the result from the queue poll request

cancelWaiters

public void cancelWaiters()

Fail all the polls that are waiting for an item on this queue. A thread blocked in one of the Future.get() methods of an asynchronous poll observes a CancellationException, and a waiter of a timed poll(long, TimeUnit) is woken without an item, the way its timeout ends the wait. Later calls to pollAsync() and poll(long, TimeUnit) do not register a waiter at all. A poll an item has already been handed over to is not failed, it completes with that item as usual.
This makes a queue that is never fed again terminate the callers that wait on it, instead of leaving them parked forever - including the timed waiters, whose own timeout the caller cannot know: the pool hands out waits of unbounded length, where waiting for the timeout would be waiting forever.

hasRegisteredWaiter

public boolean hasRegisteredWaiter()

Reports whether any caller is registered on this queue waiting for an item - through a timed poll or an asynchronous one. A releaser that decides whether an offered item has a prospective consumer cannot see these registrations through the pool's wait counter, which counts only the synchronous borrow waits.

Returns:

true if at least one caller is registered waiting for an item

remove

public boolean remove(Object e)

Specified by:

remove in interface BlockingQueue<E>

Specified by:

remove in interface Collection<E>

size

public int size()

Specified by:

size in interface Collection<E>

iterator

public Iterator<E> iterator()

Specified by:

iterator in interface Collection<E>

Specified by:

iterator in interface Iterable<E>

poll

public E poll()

Specified by:

poll in interface Queue<E>

contains

public boolean contains(Object e)

Specified by:

contains in interface BlockingQueue<E>

Specified by:

contains in interface Collection<E>

isEmpty

public boolean isEmpty()

Specified by:

isEmpty in interface Collection<E>

add

public boolean add(E e)

Specified by:

add in interface BlockingQueue<E>

Specified by:

add in interface Collection<E>

Specified by:

add in interface Queue<E>

offer

public boolean offer(E e,
 long timeout,
 TimeUnit unit)
              throws InterruptedException

Will never time out, as it invokes the offer(Object) method: the element is always inserted, so the timeout is never applied and, despite the declaration, InterruptedException is never thrown.

Specified by:

offer in interface BlockingQueue<E>

Throws:

InterruptedException

drainTo

public int drainTo(Collection<? super E> c,
 int maxElements)

Specified by:

drainTo in interface BlockingQueue<E>

Throws:

UnsupportedOperationException - - this operation is not supported

drainTo

public int drainTo(Collection<? super E> c)

Specified by:

drainTo in interface BlockingQueue<E>

Throws:

UnsupportedOperationException - - this operation is not supported

put

public void put(E e)
         throws InterruptedException

Specified by:

put in interface BlockingQueue<E>

Throws:

InterruptedException

remainingCapacity

public int remainingCapacity()

Specified by:

remainingCapacity in interface BlockingQueue<E>

take

public E take()
       throws InterruptedException

Delegates to poll(long, TimeUnit) with an effectively unbounded timeout, so the wait also ends the way that method documents for a queue whose waiters cancelWaiters() has failed.

Specified by:

take in interface BlockingQueue<E>

Throws:

InterruptedException

addAll

public boolean addAll(Collection<? extends E> c)

Specified by:

addAll in interface Collection<E>

clear

public void clear()

Specified by:

clear in interface Collection<E>

Throws:

UnsupportedOperationException - - this operation is not supported

containsAll

public boolean containsAll(Collection<?> c)

Specified by:

containsAll in interface Collection<E>

Throws:

UnsupportedOperationException - - this operation is not supported

removeAll

public boolean removeAll(Collection<?> c)

Specified by:

removeAll in interface Collection<E>

Throws:

UnsupportedOperationException - - this operation is not supported

retainAll

public boolean retainAll(Collection<?> c)

Specified by:

retainAll in interface Collection<E>

Throws:

UnsupportedOperationException - - this operation is not supported

toArray

public Object[] toArray()

Specified by:

toArray in interface Collection<E>

Throws:

UnsupportedOperationException - - this operation is not supported

toArray

public <T> T[] toArray(T[] a)

Specified by:

toArray in interface Collection<E>

Throws:

UnsupportedOperationException - - this operation is not supported

element

public E element()

Specified by:

element in interface Queue<E>

Throws:

UnsupportedOperationException - - this operation is not supported

peek

public E peek()

Specified by:

peek in interface Queue<E>

Throws:

UnsupportedOperationException - - this operation is not supported

remove

public E remove()

Specified by:

remove in interface Queue<E>

Throws:

UnsupportedOperationException - - this operation is not supported