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