Package com.apple.foundationdb.async.common

Class TopK<T>

java.lang.Object
com.apple.foundationdb.async.common.TopK<T>
Type Parameters:
T - the type of element collected
public class TopK<T> extends Object
A fixed-capacity collector that retains the top k elements offered, as ordered by a Comparator (the k that compare greatest). Once at capacity, a new element is kept only if it compares strictly greater than the current worst, which it then evicts. Unlike DistinctTopK this does not deduplicate, so equal elements may be retained more than once. Backed by a bounded min-heap, giving O(log k) add(Object).

  • Method Details

    • add

      public boolean add(@Nonnull T item)
      Offers an element to this collector. The element is kept if fewer than k elements are currently held, or if it compares strictly greater than the current worst, which it then evicts.
      Parameters:
      item - the element to offer
      Returns:
      true if the element was retained, false if it was rejected

    • toUnsortedList

      @Nonnull public List<T> toUnsortedList()
      Returns the currently retained elements in no particular order.
      Returns:
      the retained elements, unordered

    • toSortedList

      public List<T> toSortedList()
      Returns the currently retained elements ordered from greatest to least, as ranked by the comparator.
      Returns:
      the retained elements, sorted from best (greatest) to worst (least)

    • worstElement

      @Nonnull public Optional<T> worstElement()
      Returns the current worst retained element — the next one that would be evicted — or empty if none are held.
      Returns:
      the worst retained element, or Optional.empty() if the collector is empty

    • collect

      @Nonnull public CompletableFuture<List<T>> collect(AsyncIterable<T> iterable, Executor executor)
      Offers every element produced by the given iterable to this collector and returns the retained top-K as a sorted list.
      Parameters:
      iterable - the elements to offer
      executor - the executor to use for asynchronous iteration
      Returns:
      a future completing with the retained top-K elements, sorted from best to worst

    • collectRemaining

      public CompletableFuture<List<T>> collectRemaining(AsyncIterator<T> iterator, Executor executor)
      Exhausts the iterator, offering every element to this top-K collector, and returns the retained top-K elements as a sorted list.
      Parameters:
      iterator - the source of data over which to iterate. This function will exhaust the iterator.
      executor - the Executor to use for asynchronous operations
      Returns:
      a CompletableFuture completing with the retained top-K elements, sorted

    • min

      @Nonnull public static <T> TopK<T> min(@Nonnull Comparator<T> comparator, int k)
      Creates a collector that retains the k smallest elements offered, as ordered by the given comparator.
      Type Parameters:
      T - the type of element collected
      Parameters:
      comparator - the comparator defining element order
      k - the maximum number of elements to retain
      Returns:
      a new collector retaining the k smallest elements

    • max

      @Nonnull public static <T> TopK<T> max(@Nonnull Comparator<T> comparator, int k)
      Creates a collector that retains the k largest elements offered, as ordered by the given comparator.
      Type Parameters:
      T - the type of element collected
      Parameters:
      comparator - the comparator defining element order
      k - the maximum number of elements to retain
      Returns:
      a new collector retaining the k largest elements