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

public interface Spliterator<T>

Замечание API:

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

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

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

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

Пример. Вот класс (не очень полезный, кроме иллюстрации), который поддерживает массив, в котором фактические данные хранятся в чётных позициях, а не связанные тег-данные хранятся в нечётных позициях. Его 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;
     }
   }
 }

В качестве примера того, как фреймворк параллельных вычислений, такой как пакет java.util.stream, использовал бы Spliterator в параллельном вычислении, вот один способ реализации связанного параллельного forEach, который иллюстрирует основной стиль использования разбиения подзадач до тех пор, пока объём работы не станет достаточно малым для последовательного выполнения. Здесь мы предполагаем, что порядок обработки подзадач не имеет значения; различные (разветвлённые) задачи могут далее разбить и обработать элементы параллельно в неопределённом порядке. Этот пример использует 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