FairCallQueue (Apache Hadoop Common 3.5.0 API)
Description: declaration: package: org.apache.hadoop.ipc, class: FairCallQueue

Package org.apache.hadoop.ipc

# Class FairCallQueue<E extends Schedulable>

java.lang.Object
java.util.AbstractCollection<E>
java.util.AbstractQueue<E>
org.apache.hadoop.ipc.FairCallQueue<E>

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

public class FairCallQueue<E extends Schedulable> extends AbstractQueue<E> implements BlockingQueue<E>
A queue with multiple levels for each priority.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `IPC_CALLQUEUE_PRIORITY_LEVELS_DEFAULT`
  Deprecated.
  `static final String`
  `IPC_CALLQUEUE_PRIORITY_LEVELS_KEY`
  Deprecated.
  `static final org.slf4j.Logger`
  `LOG`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `FairCallQueue(int priorityLevels, int capacity, String ns, boolean serverFailOverEnabled, Configuration conf)`
  `FairCallQueue(int priorityLevels, int capacity, String ns, int[] capacityWeights, boolean serverFailOverEnabled, Configuration conf)`
  Create a FairCallQueue.
  `FairCallQueue(int priorityLevels, int capacity, String ns, Configuration conf)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `add(E e)`
  Add, put, and offer follow the same pattern: 1.
  `int`
  `drainTo(Collection<? super E> c)`
  `int`
  `drainTo(Collection<? super E> c, int maxElements)`
  drainTo defers to each sub-queue.
  `long[]`
  `getOverflowedCalls()`
  `int[]`
  `getQueueSizes()`
  `boolean`
  `isServerFailOverEnabled()`
  `Iterator<E>`
  `iterator()`
  Iterator is not implemented, as it is not needed.
  `boolean`
  `offer(E e)`
  `boolean`
  `offer(E e, long timeout, TimeUnit unit)`
  `E`
  `peek()`
  Peek, like poll, provides no strict consistency.
  `E`
  `poll()`
  poll() provides no strict consistency: it is possible for poll to return null even though an element is in the queue.
  `E`
  `poll(long timeout, TimeUnit unit)`
  `void`
  `put(E e)`
  `int`
  `remainingCapacity()`
  Returns maximum remaining capacity.
  `void`
  `setMultiplexer(RpcMultiplexer newMux)`
  `int`
  `size()`
  Size returns the sum of all sub-queue sizes, so it may be greater than capacity.
  `E`
  `take()`

  ### Methods inherited from class java.util.AbstractQueue

  `addAll, clear, element, remove`

  ### Methods inherited from class java.util.AbstractCollection

  `contains, containsAll, isEmpty, remove, removeAll, retainAll, toArray, toArray, toString`

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

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

  ### Methods inherited from interface java.util.concurrent.BlockingQueue

  `contains, remove`

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

  `addAll, clear, containsAll, equals, hashCode, isEmpty, parallelStream, removeAll, removeIf, retainAll, spliterator, stream, toArray, toArray, toArray`

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

  `forEach`

  ### Methods inherited from interface java.util.Queue

  `element, remove`

- ## Field Details

  - ### IPC_CALLQUEUE_PRIORITY_LEVELS_DEFAULT

    @Deprecated public static final int IPC_CALLQUEUE_PRIORITY_LEVELS_DEFAULT
    Deprecated.
    See Also:
      - Constant Field Values

  - ### IPC_CALLQUEUE_PRIORITY_LEVELS_KEY

    @Deprecated public static final String IPC_CALLQUEUE_PRIORITY_LEVELS_KEY
    Deprecated.
    See Also:
      - Constant Field Values

  - ### LOG

    public static final org.slf4j.Logger LOG

- ## Constructor Details

  - ### FairCallQueue

    @VisibleForTesting public FairCallQueue(int priorityLevels, int capacity, String ns, Configuration conf)

  - ### FairCallQueue

    @VisibleForTesting public FairCallQueue(int priorityLevels, int capacity, String ns, boolean serverFailOverEnabled, Configuration conf)

  - ### FairCallQueue

    public FairCallQueue(int priorityLevels, int capacity, String ns, int[] capacityWeights, boolean serverFailOverEnabled, Configuration conf)
    Create a FairCallQueue.
    Parameters:
      `priorityLevels` - the total size of all multi-level queue priority policies
      `capacity` - the total size of all sub-queues
      `ns` - the prefix to use for configuration
      `capacityWeights` - the weights array for capacity allocation among subqueues
      `serverFailOverEnabled` - whether or not to enable callqueue overflow trigger failover for stateless servers when RPC call queue is filled
      `conf` - the configuration to read from Notes: Each sub-queue has a capacity of `capacity / numSubqueues`. The first or the highest priority sub-queue has an excess capacity of `capacity % numSubqueues`

- ## Method Details

  - ### add

    public boolean add(E e)
    Add, put, and offer follow the same pattern: 1. Get the assigned priorityLevel from the call by scheduler 2. Get the nth sub-queue matching this priorityLevel 3. delegate the call to this sub-queue. But differ in how they handle overflow: - Add will move on to the next queue, throw on last queue overflow - Put will move on to the next queue, block on last queue overflow - Offer does not attempt other queues on overflow
    Specified by:
      `add` in interface `BlockingQueue<E extends Schedulable>`
    Specified by:
      `add` in interface `Collection<E extends Schedulable>`
    Specified by:
      `add` in interface `Queue<E extends Schedulable>`
    Overrides:
      `add` in class `AbstractQueue<E extends Schedulable>`

  - ### put

    public void put(E e) throws InterruptedException
    Specified by:
      `put` in interface `BlockingQueue<E extends Schedulable>`
    Throws:
      `InterruptedException`

  - ### offer

    public boolean offer(E e, long timeout, TimeUnit unit) throws InterruptedException
    Specified by:
      `offer` in interface `BlockingQueue<E extends Schedulable>`
    Throws:
      `InterruptedException`

  - ### offer

    public boolean offer(E e)
    Specified by:
      `offer` in interface `BlockingQueue<E extends Schedulable>`
    Specified by:
      `offer` in interface `Queue<E extends Schedulable>`

  - ### take

    public E take() throws InterruptedException
    Specified by:
      `take` in interface `BlockingQueue<E extends Schedulable>`
    Throws:
      `InterruptedException`

  - ### poll

    public E poll(long timeout, TimeUnit unit) throws InterruptedException
    Specified by:
      `poll` in interface `BlockingQueue<E extends Schedulable>`
    Throws:
      `InterruptedException`

  - ### poll

    public E poll()
    poll() provides no strict consistency: it is possible for poll to return null even though an element is in the queue.
    Specified by:
      `poll` in interface `Queue<E extends Schedulable>`

  - ### peek

    public E peek()
    Peek, like poll, provides no strict consistency.
    Specified by:
      `peek` in interface `Queue<E extends Schedulable>`

  - ### size

    public int size()
    Size returns the sum of all sub-queue sizes, so it may be greater than capacity. Note: size provides no strict consistency, and should not be used to control queue IO.
    Specified by:
      `size` in interface `Collection<E extends Schedulable>`
    Specified by:
      `size` in class `AbstractCollection<E extends Schedulable>`

  - ### iterator

    public Iterator<E> iterator()
    Iterator is not implemented, as it is not needed.
    Specified by:
      `iterator` in interface `Collection<E extends Schedulable>`
    Specified by:
      `iterator` in interface `Iterable<E extends Schedulable>`
    Specified by:
      `iterator` in class `AbstractCollection<E extends Schedulable>`

  - ### drainTo

    public int drainTo(Collection<? super E> c, int maxElements)
    drainTo defers to each sub-queue. Note that draining from a FairCallQueue to another FairCallQueue will likely fail, since the incoming calls may be scheduled differently in the new FairCallQueue. Nonetheless this method is provided for completeness.
    Specified by:
      `drainTo` in interface `BlockingQueue<E extends Schedulable>`

  - ### drainTo

    public int drainTo(Collection<? super E> c)
    Specified by:
      `drainTo` in interface `BlockingQueue<E extends Schedulable>`

  - ### remainingCapacity

    public int remainingCapacity()
    Returns maximum remaining capacity. This does not reflect how much you can ideally fit in this FairCallQueue, as that would depend on the scheduler's decisions.
    Specified by:
      `remainingCapacity` in interface `BlockingQueue<E extends Schedulable>`

  - ### getQueueSizes

    public int[] getQueueSizes()

  - ### getOverflowedCalls

    public long[] getOverflowedCalls()

  - ### setMultiplexer

    @VisibleForTesting public void setMultiplexer(RpcMultiplexer newMux)

  - ### isServerFailOverEnabled

    @VisibleForTesting public boolean isServerFailOverEnabled()