com.linkedin.batchable.BatchIterator Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of concurrentli Show documentation

Classes for multithreading that expand on java.util.concurrent, adding convenience, efficiency and new tools to multithreaded Java programs

There is a newer version: 1.3.2

Show newest version

/*
 * Copyright 2017 LinkedIn Corporation. All rights reserved. Licensed under the BSD-2 Clause license.
 * See LICENSE in the project root for license information.
 */

package com.linkedin.batchable;

import java.util.Iterator;

/**
 * An interface for an iterator that supports batched operations, potentially retrieving many items in a single call
 * rather than getting them one at a time.
 *
 * @param  the type of object iterated over
 */
public interface BatchIterator extends Iterator, AutoCloseable {
  @Override
  boolean hasNext();

  /**
   * Reference, but inefficient implementation for next() if you choose to implement the
   * next(T[], int, int) method below:
   *
   * T next() {
   *   T[] arr = (T[]) new Object[1];
   *   if (next(arr, 0, 1) == 0) {
   *     throw new NoSuchElementException();
   *   }
   *   return arr[0];
   * }
   */


  /**
   * Obtains the next sequence of items.
   *
   * If fewer than count items can be returned without blocking, only that number should be obtained.  However, if
   * the iterator is not exhausted, at least one item should be copied, even if blocking is required.
   *
   * The default implementation calls next() and hasNext() and can thus be relatively inefficient in many applications.
   * Classes are encouraged to override this method with an efficient implementation instead.
   *
   * @param destination the array to which the next items will be copied
   * @param offset the offset in the array at which copying begins
   * @param count the maximum number of items to copy
   *
   * @return the actual number of items copied, or 0 if the iterator is exhausted (hasNext() == false)
   */
  default int next(T[] destination, int offset, int count) {
    int copied = 0;
    while (hasNext() && copied < count) {
      destination[offset + copied] = next();
      copied++;
    }

    return copied;
  }

  /**
   * Obtains the next sequence of items.
   *
   * If fewer than destination.length items can be returned without blocking, only that number should be obtained.
   * However, if the iterator is not exhausted, at least one item should be copied, even if blocking is required.
   *
   * @param destination the array to which the next items will be copied
   *
   * @return the actual number of items copied, or 0 if the iterator is exhausted (hasNext() == false)
   */
  default int next(T[] destination) {
    return next(destination, 0, destination.length);
  }

  /**
   * At least this many items can be read without blocking with high probability (e.g. acquiring a rarely-contested lock
   * would not qualify as "blocking" because the thread would only very rarely need to park).
   *
   * Note that this is a more strict definition than that for the similar InputStream method of the same name,
   * as the return value is strictly a lower-bound, not simply an "estimate".
   *
   * If any size read could or would block, 0 should be returned.  0 will also be returned if the end of stream has been
   * reached.
   *
   * @return the number of items that can (with certainty) be returned without blocking.
   */
  long available();

  /**
   * "Closes" this iterator and releases its resources.  Further operations on the iterator after being
   * closed are undefined.
   */
  @Override
  void close();
}