net.i2p.router.util

## Class PriBlockingQueue<E extends PQEntry>

- java.lang.Object
- - java.util.AbstractCollection<E>
  - - java.util.AbstractQueue<E>
    - - java.util.concurrent.PriorityBlockingQueue<E>
      - - net.i2p.router.util.PriBlockingQueue<E>

- Type Parameters:
    `E` - type of elements held in this queue, extending `PQEntry`
  All Implemented Interfaces:
    Serializable, Iterable<E>, Collection<E>, BlockingQueue<E>, Queue<E>
  Direct Known Subclasses:
    CoDelPriorityBlockingQueue

      public class PriBlockingQueue<E extends PQEntry>
      extends PriorityBlockingQueue<E>

  Priority blocking queue with bounded capacity and FIFO ordering within priority levels.

  Extends PriorityBlockingQueue to provide bounded capacity with FIFO ordering for elements sharing the same priority. Entries extend PQEntry to include sequence numbers for insertion ordering.

  Applies sequence timestamps on insertion to ensure FIFO behavior within same priority level while maintaining priority-based ordering. Capacity is controlled by configuration properties to prevent unbounded growth and enable backpressure management.

  Thread-safe implementation suitable for concurrent producer-consumer scenarios with comprehensive statistics tracking and performance monitoring.

  See Also:
    Serialized Form

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected I2PAppContext` | `_context`
    `protected Log` | `_log`
    `protected String` | `_name`
    `protected static int` | `DEFAULT_BACKLOG_SIZE` Default backlog and max size depending on system speed.
    `protected static int` | `DEFAULT_MAX_SIZE`
    `static String` | `PROP_BACKLOG_SIZE`
    `static String` | `PROP_MAX_SIZE` Configuration property keys for max size and backlog thresholds.
    `protected static long[]` | `RATES` Time windows for rate statistics in milliseconds.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PriBlockingQueue(I2PAppContext ctx, String name, int initialCapacity)` Constructs a new priority blocking queue with the given initial capacity.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `isBacklogged()` Checks if the queue size is above the backlog threshold, indicating potential congestion or overload.
    `boolean` | `offer(E o)` Inserts the specified element into this queue if it is not full, applying sequence timestamp to ensure FIFO ordering within priority.
    `protected void` | `timestamp(E o)` Assigns a unique sequence number to the element to maintain FIFO ordering among elements of the same priority.

    - ### Methods inherited from class java.util.concurrent.PriorityBlockingQueue

      `add, clear, comparator, contains, drainTo, drainTo, iterator, offer, peek, poll, poll, put, remainingCapacity, remove, size, spliterator, take, toArray, toArray, toString`

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

      `addAll, element, remove`

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

      `containsAll, isEmpty, removeAll, retainAll`

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

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

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

      `element, remove`

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

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

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

      `forEach`

- - ### Field Detail

    - #### _context

          protected final transient I2PAppContext _context

    - #### _log

          protected final transient Log _log

    - #### _name

          protected final String _name

    - #### DEFAULT_BACKLOG_SIZE

          protected static final int DEFAULT_BACKLOG_SIZE

      Default backlog and max size depending on system speed.

    - #### DEFAULT_MAX_SIZE

          protected static final int DEFAULT_MAX_SIZE

    - #### PROP_BACKLOG_SIZE

          public static final String PROP_BACKLOG_SIZE

      See Also:
        Constant Field Values

    - #### PROP_MAX_SIZE

          public static final String PROP_MAX_SIZE

      Configuration property keys for max size and backlog thresholds.
      See Also:
        Constant Field Values

    - #### RATES

          protected static final long[] RATES

      Time windows for rate statistics in milliseconds.

  - ### Constructor Detail

    - #### PriBlockingQueue

          public PriBlockingQueue(I2PAppContext ctx,
                                  String name,
                                  int initialCapacity)

      Constructs a new priority blocking queue with the given initial capacity. The queue is bounded by a configurable max size read once at construction.
      Parameters:
        `ctx` - the I2P application context
        `name` - a name for this queue instance (used in stats)
        `initialCapacity` - the initial capacity for the priority queue

  - ### Method Detail

    - #### isBacklogged

          public boolean isBacklogged()

      Checks if the queue size is above the backlog threshold, indicating potential congestion or overload.
      Returns:
        true if queue size is above backlog size threshold, false otherwise

    - #### offer

          public boolean offer(E o)

      Inserts the specified element into this queue if it is not full, applying sequence timestamp to ensure FIFO ordering within priority. Returns false if the queue has reached its maximum size.
      Specified by:
        `offer` in interface `BlockingQueue<E extends PQEntry>`
      Specified by:
        `offer` in interface `Queue<E extends PQEntry>`
      Overrides:
        `offer` in class `PriorityBlockingQueue<E extends PQEntry>`
      Parameters:
        `o` - the element to add
      Returns:
        true if successfully added, false if queue is full

    - #### timestamp

          protected void timestamp(E o)

      Assigns a unique sequence number to the element to maintain FIFO ordering among elements of the same priority.
      Parameters:
        `o` - the element to timestamp