Class DistributedPriorityQueue<V>

java.lang.Object
com.loomcache.server.datastructures.DistributedPriorityQueue<V>
Type Parameters:
V - the type of elements held in this queue
public class DistributedPriorityQueue<V> extends Object
Distributed Priority Queue — priority queue backed by ConcurrentSkipListMap.

Ordering:

  • Items are sorted by priority (lower number = higher priority)
  • Within the same priority, items are ordered FIFO (insertion order)

Operations:

  • offer: add an item with a specific priority
  • offer (default priority): add an item with default priority 5
  • poll: remove and return highest priority item (FIFO within same priority)
  • peek: view the highest priority item without removing
  • size: number of items
  • drainTo: bulk drain into a collection

Thread-safe via ConcurrentSkipListMap and AtomicLong for ordering. Uses records and sealed classes per Java 25 best practices.

Since:
1.0

  • Constructor Details

    • DistributedPriorityQueue

      public DistributedPriorityQueue(String name, int instanceNumber)

    • DistributedPriorityQueue

      public DistributedPriorityQueue(String name, int instanceNumber, @Nullable Comparator<? super V> itemComparator, @Nullable String priorityComparatorClassName)

    • DistributedPriorityQueue

      public DistributedPriorityQueue(String name, int instanceNumber, int maxCapacity)

    • DistributedPriorityQueue

      public DistributedPriorityQueue(String name, int instanceNumber, int maxCapacity, @Nullable Comparator<? super V> itemComparator, @Nullable String priorityComparatorClassName)

  • Method Details

    • getMaxCapacity

      public int getMaxCapacity()

    • offer

      public boolean offer(V item, int priority)
      Add an item with the specified priority. Lower priority number = higher priority.
      Parameters:
      item - the item to add
      priority - the priority (lower = higher priority)
      Returns:
      true if successfully added, false if capacity is full

    • offer

      public boolean offer(V item)
      Add an item with the default priority (5).
      Parameters:
      item - the item to add
      Returns:
      true if successfully added, false if capacity is full

    • poll

      public @Nullable V poll()
      Remove and return the highest priority item (lowest priority number). Within the same priority, FIFO order is preserved.
      Returns:
      the highest priority item, or null if the queue is empty

    • peek

      public @Nullable V peek()
      View the highest priority item without removing it.
      Returns:
      the highest priority item, or null if the queue is empty

    • size

      public long size()
      Returns the number of items in the queue.
      Returns:
      the size of the queue

    • isEmpty

      public boolean isEmpty()
      Check if the queue is empty.
      Returns:
      true if the queue contains no items

    • clear

      public void clear()
      Remove all items from the queue.

    • drainTo

      public int drainTo(Collection<? super V> target, int maxElements)
      Drain up to maxElements from the queue into the target collection. Items are removed in priority order (highest priority first, FIFO within same priority).
      Parameters:
      target - the collection to add drained elements to
      maxElements - the maximum number of elements to drain (0 = unlimited)
      Returns:
      the number of elements drained

    • toList

      public List<V> toList()
      Return a non-destructive copy of all items in the queue. Items are listed in priority order (highest priority first).
      Returns:
      an unmodifiable list of queue contents

    • snapshotForPersistence

      public List<DistributedPriorityQueue.PriorityQueueSnapshotEntry<V>> snapshotForPersistence()
      Return the full persistence state, including priorities and insertion sequence.

      User-facing views only expose values; Raft snapshots need the hidden priority/sequence metadata to preserve ordering after installSnapshot.

    • getSequenceCounterForPersistence

      public long getSequenceCounterForPersistence()

    • getTotalAddedForPersistence

      public long getTotalAddedForPersistence()

    • getTotalRemovedForPersistence

      public long getTotalRemovedForPersistence()

    • restoreFromSnapshot

      public void restoreFromSnapshot(List<DistributedPriorityQueue.PriorityQueueSnapshotEntry<V>> entries, long restoredSequenceCounter, long restoredTotalAdded, long restoredTotalRemoved)

    • peekAll

      public List<V> peekAll()
      Return all items in the queue in priority order without removing them.
      Returns:
      unmodifiable list of all items in priority order

    • removeIf

      public int removeIf(Predicate<? super V> predicate)
      Remove all items matching the given predicate.
      Parameters:
      predicate - the predicate to test items
      Returns:
      the number of items removed

    • contains

      public boolean contains(V item)
      Check if an item exists in the queue.
      Parameters:
      item - the item to check
      Returns:
      true if the item is in the queue

    • getPriority

      public int getPriority(V item)
      Get the current priority of an item.
      Parameters:
      item - the item to get priority for
      Returns:
      the priority, or -1 if the item is not in the queue

    • changePriority

      public boolean changePriority(V item, int newPriority)
      Change the priority of an existing item.
      Parameters:
      item - the item to change priority for
      newPriority - the new priority (lower = higher priority)
      Returns:
      true if the item was found and priority changed, false if not found

    • addAll

      public int addAll(Collection<? extends V> items, int priority)
      Add multiple items with the same priority.
      Parameters:
      items - the items to add
      priority - the priority for all items
      Returns:
      the number of items successfully added

    • pollBatch

      public List<V> pollBatch(int count)
      Poll up to count items from the queue.
      Parameters:
      count - the maximum number of items to poll
      Returns:
      list of polled items in priority order (empty if queue is empty)

    • merge

      public int merge(DistributedPriorityQueue<V> other)
      Merge another DistributedPriorityQueue into this one. All items from the other queue are added to this queue with their original priorities.
      Parameters:
      other - the other priority queue to merge
      Returns:
      the number of items successfully merged

    • toSortedList

      public List<V> toSortedList()
      Return all elements sorted by priority without removing them. Items are returned in priority order (highest priority first, FIFO within same priority).
      Returns:
      unmodifiable list of all items sorted by priority

    • getMinPriority

      public int getMinPriority()
      Get the minimum priority value in the queue.
      Returns:
      the minimum priority value, or Integer.MAX_VALUE if queue is empty

    • getMaxPriority

      public int getMaxPriority()
      Get the maximum priority value in the queue.
      Returns:
      the maximum priority value, or Integer.MIN_VALUE if queue is empty

    • getStats

      public DistributedPriorityQueue.PriorityQueueStats getStats()
      Get statistics snapshot of the priority queue.
      Returns:
      PriorityQueueStats containing aggregated statistics