Интерфейс 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:

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

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

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

• Источник не может подвергаться структурным изменениям.
  Например, экземпляр CopyOnWriteArrayList является неизменяемым источником. Spliterator, созданный из источника, сообщает о характеристике IMMUTABLE.
• Источник управляет одновременными изменениями.
  Например, набор ключей ConcurrentHashMap является конкурирующим источником. Spliterator, созданный из источника, сообщает о характеристике CONCURRENT.
• Изменяемый источник предоставляет Spliterator с отложенной привязкой и быстродействующий 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