# 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