Package org.apache.tomcat.jdbc.pool

## 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:
    `java.lang.Iterable<E>`, `java.util.Collection<E>`, `java.util.concurrent.BlockingQueue<E>`, `java.util.Queue<E>`

      public class MultiLockFairBlockingQueue<E>
      extends java.lang.Object
      implements java.util.concurrent.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>` |
    `protected class` | `MultiLockFairBlockingQueue.FairIterator` |
    `protected class` | `MultiLockFairBlockingQueue.ItemFuture<T>` |

  - ### Constructor Summary

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

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `add​(E e)` |
    `boolean` | `addAll​(java.util.Collection<? extends E> c)` |
    `void` | `clear()`
    `boolean` | `contains​(java.lang.Object e)` |
    `boolean` | `containsAll​(java.util.Collection<?> c)`
    `int` | `drainTo​(java.util.Collection<? super E> c)`
    `int` | `drainTo​(java.util.Collection<? super E> c, int maxElements)`
    `E` | `element()`
    `int` | `getNextPoll()` |
    `int` | `getNextPut()` |
    `boolean` | `isEmpty()` |
    `java.util.Iterator<E>` | `iterator()` |
    `boolean` | `offer​(E e)` | Will always return true, queue is unbounded.
    `boolean` | `offer​(E e, long timeout, java.util.concurrent.TimeUnit unit)` | Will never timeout, as it invokes the `offer(Object)` method.
    `E` | `peek()`
    `E` | `poll()` |
    `E` | `poll​(long timeout, java.util.concurrent.TimeUnit unit)` | Fair retrieval of an object in the queue.
    `java.util.concurrent.Future<E>` | `pollAsync()` | Request an item from the queue asynchronously
    `void` | `put​(E e)` |
    `int` | `remainingCapacity()` |
    `E` | `remove()`
    `boolean` | `remove​(java.lang.Object e)` |
    `boolean` | `removeAll​(java.util.Collection<?> c)`
    `boolean` | `retainAll​(java.util.Collection<?> c)`
    `int` | `size()` |
    `E` | `take()` |
    `java.lang.Object[]` | `toArray()`
    `<T> T[]` | `toArray​(T[] a)`

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface java.util.Collection

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

    - ### Methods inherited from interface java.lang.Iterable

      `forEach`

- - ### Constructor Detail

    - #### MultiLockFairBlockingQueue

          public MultiLockFairBlockingQueue()

      Creates a new fair blocking queue.

  - ### Method Detail

    - #### getNextPut

          public int getNextPut()

    - #### getNextPoll

          public int getNextPoll()

    - #### offer

          public boolean offer​(E e)

      Will always return true, queue is unbounded.
      Specified by:
        `offer` in interface `java.util.concurrent.BlockingQueue<E>`
      Specified by:
        `offer` in interface `java.util.Queue<E>`

    - #### offer

          public boolean offer​(E e,
                               long timeout,
                               java.util.concurrent.TimeUnit unit)
                        throws java.lang.InterruptedException

      Will never timeout, as it invokes the `offer(Object)` method. Once a lock has been acquired, the
      Specified by:
        `offer` in interface `java.util.concurrent.BlockingQueue<E>`
      Throws:
        `java.lang.InterruptedException`

    - #### poll

          public E poll​(long timeout,
                        java.util.concurrent.TimeUnit unit)
                 throws java.lang.InterruptedException

      Fair retrieval of an object in the queue. Objects are returned in the order the threads requested them.
      Specified by:
        `poll` in interface `java.util.concurrent.BlockingQueue<E>`
      Throws:
        `java.lang.InterruptedException`

    - #### pollAsync

          public java.util.concurrent.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​(java.lang.Object e)

      Specified by:
        `remove` in interface `java.util.concurrent.BlockingQueue<E>`
      Specified by:
        `remove` in interface `java.util.Collection<E>`

    - #### size

          public int size()

      Specified by:
        `size` in interface `java.util.Collection<E>`

    - #### iterator

          public java.util.Iterator<E> iterator()

      Specified by:
        `iterator` in interface `java.util.Collection<E>`
      Specified by:
        `iterator` in interface `java.lang.Iterable<E>`

    - #### poll

          public E poll()

      Specified by:
        `poll` in interface `java.util.Queue<E>`

    - #### contains

          public boolean contains​(java.lang.Object e)

      Specified by:
        `contains` in interface `java.util.concurrent.BlockingQueue<E>`
      Specified by:
        `contains` in interface `java.util.Collection<E>`

    - #### add

          public boolean add​(E e)

      Specified by:
        `add` in interface `java.util.concurrent.BlockingQueue<E>`
      Specified by:
        `add` in interface `java.util.Collection<E>`
      Specified by:
        `add` in interface `java.util.Queue<E>`

    - #### drainTo

          public int drainTo​(java.util.Collection<? super E> c,
                             int maxElements)

      Specified by:
        `drainTo` in interface `java.util.concurrent.BlockingQueue<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - - this operation is not supported

    - #### drainTo

          public int drainTo​(java.util.Collection<? super E> c)

      Specified by:
        `drainTo` in interface `java.util.concurrent.BlockingQueue<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - - this operation is not supported

    - #### put

          public void put​(E e)
                   throws java.lang.InterruptedException

      Specified by:
        `put` in interface `java.util.concurrent.BlockingQueue<E>`
      Throws:
        `java.lang.InterruptedException`

    - #### remainingCapacity

          public int remainingCapacity()

      Specified by:
        `remainingCapacity` in interface `java.util.concurrent.BlockingQueue<E>`

    - #### take

          public E take()
                 throws java.lang.InterruptedException

      Specified by:
        `take` in interface `java.util.concurrent.BlockingQueue<E>`
      Throws:
        `java.lang.InterruptedException`

    - #### addAll

          public boolean addAll​(java.util.Collection<? extends E> c)

      Specified by:
        `addAll` in interface `java.util.Collection<E>`

    - #### clear

          public void clear()

      Specified by:
        `clear` in interface `java.util.Collection<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - - this operation is not supported

    - #### containsAll

          public boolean containsAll​(java.util.Collection<?> c)

      Specified by:
        `containsAll` in interface `java.util.Collection<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - - this operation is not supported

    - #### isEmpty

          public boolean isEmpty()

      Specified by:
        `isEmpty` in interface `java.util.Collection<E>`

    - #### removeAll

          public boolean removeAll​(java.util.Collection<?> c)

      Specified by:
        `removeAll` in interface `java.util.Collection<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - - this operation is not supported

    - #### retainAll

          public boolean retainAll​(java.util.Collection<?> c)

      Specified by:
        `retainAll` in interface `java.util.Collection<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - - this operation is not supported

    - #### toArray

          public java.lang.Object[] toArray()

      Specified by:
        `toArray` in interface `java.util.Collection<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - - this operation is not supported

    - #### toArray

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

      Specified by:
        `toArray` in interface `java.util.Collection<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - - this operation is not supported

    - #### element

          public E element()

      Specified by:
        `element` in interface `java.util.Queue<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - - this operation is not supported

    - #### peek

          public E peek()

      Specified by:
        `peek` in interface `java.util.Queue<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - - this operation is not supported

    - #### remove

          public E remove()

      Specified by:
        `remove` in interface `java.util.Queue<E>`
      Throws:
        `java.lang.UnsupportedOperationException` - - this operation is not supported