Интерфейс Spliterator<T>

public interface Spliterator<T>

Примечание API:

Сплитераторы, как и Iteratorы, предназначены для обхода элементов источника. API Spliterator разработан для поддержки эффективного параллельного обхода в дополнение к последовательному обходу: он поддерживает как разбиение, так и итерацию по отдельным элементам. Кроме того, протокол доступа к элементам через Spliterator разработан так, чтобы накладные расходы на каждый элемент были меньше, чем у Iterator, и чтобы избежать неизбежной гонки, возникающей при использовании отдельных методов для hasNext() и next().

Для изменяемых источников структурное вмешательство в источник (добавление, замена или удаление элементов) между моментом привязки Spliterator к источнику данных и завершением обхода может привести к произвольному и недетерминированному поведению. Например, такое вмешательство приведет к произвольным недетерминированным результатам при использовании платформы java.util.stream.

Структурное вмешательство в источник можно обрабатывать следующими способами (примерно в порядке убывания предпочтительности):

• Структурное вмешательство в источник невозможно.
  Например, экземпляр CopyOnWriteArrayList является неизменяемым источником. Созданный на основе этого источника Spliterator сообщает характеристику IMMUTABLE.
• Источник самостоятельно обрабатывает параллельные изменения.
  Например, множество ключей ConcurrentHashMap является параллельным источником. Созданный на основе этого источника Spliterator сообщает характеристику CONCURRENT.
• Изменяемый источник предоставляет Spliterator с отложенной привязкой и свойством fail-fast.
  Отложенная привязка сокращает период, в течение которого вмешательство может повлиять на вычисления; свойство fail-fast по возможности обнаруживает структурное вмешательство после начала обхода и выбрасывает ConcurrentModificationException. Например, ArrayList и многие другие непараллельные классы Collection в JDK предоставляют Spliterator с отложенной привязкой и свойством fail-fast.
• Изменяемый источник предоставляет Spliterator без отложенной привязки, но со свойством fail-fast.
  Такой источник повышает вероятность выбрасывания ConcurrentModificationException, поскольку период потенциального вмешательства больше.
• Изменяемый источник предоставляет Spliterator с отложенной привязкой, но без свойства fail-fast.
  После начала обхода источник может вести себя произвольно и недетерминированно, поскольку вмешательство не обнаруживается.
• Изменяемый источник предоставляет Spliterator без отложенной привязки и без свойства fail-fast.
  Такой источник повышает риск произвольного недетерминированного поведения, поскольку необнаруженное вмешательство может произойти после создания.

Пример. Ниже приведен класс (не слишком полезный, кроме как для иллюстрации), который хранит массив: фактические данные размещаются в четных ячейках, а не связанные с ними метаданные — в нечетных. Его Spliterator игнорирует метаданные.

class TaggedArray<T> {
  private final Object[] elements; // immutable after construction
  TaggedArray(T[] data, Object[] tags) {
    int size = data.length;
    if (tags.length != size) throw new IllegalArgumentException();
    this.elements = new Object[2 * size];
    for (int i = 0, j = 0; i < size; ++i) {
      elements[j++] = data[i];
      elements[j++] = tags[i];
    }
  }

  public Spliterator<T> spliterator() {
    return new TaggedArraySpliterator<>(elements, 0, elements.length);
  }

  static class TaggedArraySpliterator<T> implements Spliterator<T> {
    private final Object[] array;
    private int origin; // current index, advanced on split or traversal
    private final int fence; // one past the greatest index

    TaggedArraySpliterator(Object[] array, int origin, int fence) {
      this.array = array; this.origin = origin; this.fence = fence;
    }

    public void forEachRemaining(Consumer<? super T> action) {
      for (; origin < fence; origin += 2)
        action.accept((T) array[origin]);
    }

    public boolean tryAdvance(Consumer<? super T> action) {
      if (origin < fence) {
        action.accept((T) array[origin]);
        origin += 2;
        return true;
      }
      else // cannot advance
        return false;
    }

    public Spliterator<T> trySplit() {
      int lo = origin; // divide range in half
      int mid = ((lo + fence) >>> 1) & ~1; // force midpoint to be even
      if (lo < mid) { // split out left half
        origin = mid; // reset this Spliterator's origin
        return new TaggedArraySpliterator<>(array, lo, mid);
      }
      else       // too small to split
        return null;
    }

    public long estimateSize() {
      return (long)((fence - origin) / 2);
    }

    public int characteristics() {
      return ORDERED | SIZED | IMMUTABLE | SUBSIZED;
    }
  }
}

В качестве примера использования Spliterator параллельной вычислительной платформой, такой как пакет java.util.stream, приведен один из способов реализации связанного с ним параллельного forEach, иллюстрирующий основной идиоматический способ применения: разделение на подзадачи продолжается до тех пор, пока предполагаемый объем работы не станет достаточно малым для последовательного выполнения. Здесь предполагается, что порядок обработки подзадач не имеет значения; разные задачи (созданные с помощью fork) могут дополнительно разделять и обрабатывать элементы параллельно в неопределенном порядке. В этом примере используется CountedCompleter; аналогичным образом можно использовать и другие конструкции параллельных задач.

static <T> void parEach(TaggedArray<T> a, Consumer<T> action) {
  Spliterator<T> s = a.spliterator();
  long targetBatchSize = s.estimateSize() / (ForkJoinPool.getCommonPoolParallelism() * 8);
  new ParEach(null, s, action, targetBatchSize).invoke();
}

static class ParEach<T> extends CountedCompleter<Void> {
  final Spliterator<T> spliterator;
  final Consumer<T> action;
  final long targetBatchSize;

  ParEach(ParEach<T> parent, Spliterator<T> spliterator,
          Consumer<T> action, long targetBatchSize) {
    super(parent);
    this.spliterator = spliterator; this.action = action;
    this.targetBatchSize = targetBatchSize;
  }

  public void compute() {
    Spliterator<T> sub;
    while (spliterator.estimateSize() > targetBatchSize &&
           (sub = spliterator.trySplit()) != null) {
      addToPendingCount(1);
      new ParEach<>(this, sub, action, targetBatchSize).fork();
    }
    spliterator.forEachRemaining(action);
    propagateCompletion();
  }
}

Примечание по реализации:

Если логическое системное свойство org.openjdk.java.util.stream.tripwire установлено в true, при упаковке примитивных значений во время работы со специализациями для примитивных типов выводятся диагностические предупреждения.

С момента появления:

1.8

См. также:

• Collection