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

Параметры типа:

T - тип элементов, возвращаемых этим Spliterator

Все известные подинтерфейсы:

Spliterator.OfDouble, Spliterator.OfInt, Spliterator.OfLong, Spliterator.OfPrimitive<T,T_CONS,T_SPLITR>

Все известные реализующие классы:

Spliterators.AbstractDoubleSpliterator, Spliterators.AbstractIntSpliterator, Spliterators.AbstractLongSpliterator, Spliterators.AbstractSpliterator

public interface Spliterator<T>

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

Итераторы Spliterator, как Iterators, предназначены для обхода элементов источника. 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