# Class MultiLockFairBlockingQueue<E>

java.lang.Object
org.apache.tomcat.jdbc.pool.MultiLockFairBlockingQueue<E>

Type Parameters:
  `E` - Type of element in the queue

All Implemented Interfaces:
  `Iterable<E>, Collection<E>, BlockingQueue<E>, Queue<E>`

public class MultiLockFairBlockingQueue<E> extends Object implements BlockingQueue<E>
EXPERIMENTAL AND NOT YET COMPLETE! An implementation of a blocking queue with fairness waiting and lock dispersal to avoid contention. invocations to method poll(...) will get handed out in the order they were received. Locking is fine grained, a shared lock is only used during the first level of contention, waiting is done in a lock per thread basis so that order is guaranteed once the thread goes into a suspended monitor state.
Not all of the methods of the `BlockingQueue` are implemented.

## Nested Class Summary

Nested Classes
Modifier and Type
Class
Description
`protected class`
`MultiLockFairBlockingQueue.ExchangeCountDownLatch<T>`
Count down latch that can exchange information.
`protected class`
`MultiLockFairBlockingQueue.FairIterator`
Iterator safe from concurrent modification exceptions.
`protected class`
`MultiLockFairBlockingQueue.ItemFuture<T>`
Future for an item in the queue.

## Constructor Summary

Constructors
Constructor
Description
`MultiLockFairBlockingQueue()`
Creates a new fair blocking queue.

## Method Summary

Modifier and Type
Method
Description
`boolean`
`add(E e)`
`boolean`
`addAll(Collection<? extends E> c)`
`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()`
`int`
`getNextPoll()`
Get the next poll index.
`int`
`getNextPut()`
Get the next put index.
`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 timeout, as it invokes the `offer(Object)` method.
`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()`
`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

### MultiLockFairBlockingQueue

public MultiLockFairBlockingQueue()
Creates a new fair blocking queue.

## Method Details

### getNextPut

public int getNextPut()
Get the next put index.

Returns:
  the next put index

### getNextPoll

public int getNextPoll()
Get the next poll index.

Returns:
  the next poll index

### 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>`

### offer

public boolean offer(E e, long timeout, TimeUnit unit) throws InterruptedException
Will never timeout, as it invokes the `offer(Object)` method. Once a lock has been acquired, the

Specified by:
  `offer` in interface `BlockingQueue<E>`
Throws:
  `InterruptedException`

### 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.

Specified by:
  `poll` in interface `BlockingQueue<E>`
Throws:
  `InterruptedException`

### pollAsync

public Future<E> pollAsync()
Request an item from the queue asynchronously

Returns:
  - a future pending the result from the queue poll request

### 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>`

### 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>`

### 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

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

### isEmpty

public boolean isEmpty()

Specified by:
  `isEmpty` in interface `Collection<E>`

### 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