Spliterator <T> Interface

Documentation

• A source for objects from among the elements of a partition traversed and
• Spliterator a covering element source can be an array, Collection, IO channel generator function
• A Spliterator a traverse element can be a (tryAdvance ()), the block may be sequentially traverse (forEachRemaining ())
• A Spliterator trySplit elements thereof may be used to form additional partition Spliterator, in parallel operations
• Spliterator used in the operation but can not be divided, or segmented result highly unbalanced or ineffective, then operation can not benefit from them in parallel
• And dividing consumed will traverse elements, each corresponding to its Spliterator only calculates a single block
• Spliterator also a report to a configured with the set characteristic value and the characteristic values ​​of the source elements which are: ORDERED, DISTINCT, SORTED, SIZED, NONNULL, IMMUTABLE, CONCURRENT, SUBSIZED
• These characteristics may be Spliterator user call, or to simplify the calculation Laid
• The property values ​​are identified by the bit manipulation
• Part characteristic value method additionally defining behavior
  • Such as: ORDER, they must follow the traversal methods defined in the document good order
• The future may also define a new property values, and therefore does not realize the word than eight characteristic values ​​should give new meaning
• When a Spliterator not contain `IMMUTABLE` or` CONCURRENT` properties, hoping to make the following documented strategy considerations
  • When Spliterator bound to the source element, the element needs to be detected in the structure
• Rapid-Fail
  • A delay bound Spliterator in the first traversal, or first division for the first time or when bound to a query on the source size, rather than binding in its creation
  • A non-binding Spliterator delay when a method of constructing the first call or any ie binding
  • Before binding, if the source is modified, the changes will be reflected when traversing Spliterator
  • When bound to Spliterator, continue to make changes to the source, will throw ConcurrentModificationException
  • Spliterator defined above is referred to as "fast failure" (fail-fast)
• A method of traversing block forEachRemaining Spliterator () will be optimized traversal, and changes in the structure after checking all of the elements traversed to complete, rather than one by one to check when traversing element
• Spliterator by estimateSize () method to get an estimate of the number of elements to be traversed
  • Ideally, if the characteristic values ​​included `SIZED`, the calculated results estimateSize will necessarily accurate
  • However, even if the estimated value is obtained, but the result of the operation of the source or helpful
    • For example, it can help us to decide whether to block or parallel traversal
• Despite a series of significant practical function of parallel algorithms, but does not require Spliterator thread-safe; contrast, the use of the implementation of parallel algorithms Spliterator, you need to ensure the same time only one thread access Spliterator
  • This generally easy to achieve by way of `serial thread-confinement`
  • If a thread calls trySplit (), it will be Spliterator transferred to another thread, another thread may be further divided or traverse this Spliterator
  • When two or more threads simultaneously operating the same Spliterator, or split traversal behavior is undefined
  • If the original thread needs to Spliterator handed over to other threads to deal with, then transfer the best place in all operating elements are completed by tryAdvance before (Consumer) method of consumption is complete, because certain properties? Only (such as accuracy estimateSize () method) before checking begins traversal
• Subtype native specialized Spliterator provides OfInt, OfLong, OfDouble
  • Spliterator subtype default implementation by tryAdvance (Consumer) and forEachRemaining (Consumer), the value of the original raw type of package to the corresponding packaging
  • The packaging process will weaken the performance advantages portion
  • To avoid packing, should be used based on the native values, e.g.
    • Relative to Spliterator.OfInt.tryAdvance (Consumer), should be more priority Spliterator.OfInt.tryAdvance (IntConsumer)
      
    • Using native traversal value based method of packing, and does not affect the value of the order
• apiNote
  • Iterator Spliterator and as a source for the traversing element among
    • Spliterator API designed to support decomposition and iterative single element, so that in addition to support serial operation, but also supports efficient parallel operation
    • In addition, the protocol to access the elements via Spliterator, so that the operating system resources consumed by each element is smaller than the Iterator, and avoid competition arise when using next () and hasNext () resources (concurrency)
  • For variable sources, in Spliterator bound to a data source to traverse the end of the period, due to structural changes if the data source element to add, replace or delete a result of the emergence of behavior will likely appear arbitrary and uncertain
    • For example: This modification will generate arbitrary in the use of `java.util.stream` framework, inconclusive results
  • Modifications in the structure of a source may be managed by several ways
    • The structure of the source can not be modified
      • For example: `java.util.concurrent.CopyOnWriteArrayList` is an immutable source, created by this source Spliterator returns a characteristic value` IMMUTABLE`
    • To manage concurrent source itself
      • For example: the collection of key java.util.concurrent.ConcurrentHashMap is a concurrent source, created by this source Spliterator returns a value characteristic CONCURRENT
    • Variable source to provide a "late binding" and "fast failure" Spliterator
      • When the changes will affect the calculation, late binding will narrow window
      • Rapid failure detection, when the source has begun to traverse, if detected structural modifications will be thrown ConcurrentModificationException
      • For example: ArrayList collection and other "non-concurrent", will provide a "late binding" and "fast failure" Spliterator
    • Variable source to provide a "non-lazy binding" and "fast failure" Spliterator
      • Source will increase the likelihood of `ConcurrentModificationException` thrown out, because of the potential modification of the time window is magnified
    • Variable source to provide a "late binding" and "non-fast failure" Spliterator
      • After traversing the data source will be arbitrary and uncertain risk behaviors occur, that modification is uncertain
    • Variable source to provide a "non-lazy binding" and "non-fast failure" Spliterator
      • Source will increase the risk behavior appears arbitrary and uncertain, because there will be uncertainty modification action after construction
• implNote
  • If the boolean org.openjdk.java.util.stream.tripwire system value set to true, the operation performed when the boxing operation Laid facilitator native type, the system will report the diagnostic warnings
    

method

• boolean tryAdvance(Consumer<? super T> action)
  • If there are remaining elements, it will perform a given action, while returns true, false otherwise
    
  • If `ORDER` Spliterator having characteristics, the action will be performed in a specified order
  • Any exception thrown by the action, all will be passed to the caller
• default void forEachRemaining(Consumer<? super T> action)
  • They are to perform for each of the remaining elements of action given the current thread execution in a serial manner until all elements are executed or thrown actions
    
  • If Spliterator ORDER having characteristics, the action will be performed in a specified order
  • Any exception thrown by the action, all will be passed to the caller
  • The default implementation will be repeated calls tryAdvance (), until you return false, if necessary, the need to be rewritten
• Spliterator<T> trySplit()
  • If this can be divided Spliterator is returned Spliterator containing a portion of the element, and then returned from this method, the element Spliterator returned from this method, and separated from the current of Spliterator
    
  • If the current Spliterator has ORDERED features, then return out Spliterator must also have characteristics ORDERED
  • Unless the current Spliterator covers unlimited elements, otherwise called repeatedly trySplit () will eventually return null
  • If the return value is not empty
    • Two Spliterator before division, estimateSize values ​​obtained () must be greater than or equal to the divided by estimateSize () values ​​obtained
      
    • And the value, if the current `SUBSIZE` Spliterator having properties, use estimateSize () value is obtained, must be equal to two divided by Spliterator estimateSize () is obtained and
  • For some reason, this method returns null: no elements traverse has begun, there is a limit data structures, some of the considerations of efficiency
  • apiNote
  • trySplit () `(not traversed) in the ideal case, the elements will be halved on average, allowed to equilibrate for Parallel Computing
  • Many a departure from this ideal state case is still able to maintain high efficiency
    • For example: approximately approximately balanced cutting a tree, or to a leaf node may contain one or two elements of the tree can not be further divided
      
    • However, poorly balanced division will lead to a sharp decline in the efficiency of the parallel
• long estimateSize()
  • Returns the number of elements will be operated forEachRemaining estimates, if the element is infinite, unknown, or calculated cost prohibitive, it will return a maximum value (MAX_VALUE)
    
  • If a Spliterator having SIZED properties and is not split or traverse, or having SUBSIZED Spliterator this characteristic, and is not divided traversal, the return value must be the exact number of all elements in a complete traversal encountered
  • Otherwise, this estimate would be inaccurate, but certainly with calls `trySplit ()` rather smaller and smaller
  • apiNote
  • While accurate estimates do not, but it is often useful, and calculates the cost is not high
  • For example: an approximately balanced binary tree of a sub-spliterator, estimates will return half of its parent node; if not root Spliterator maintain an accurate value, it will be based on the maximum depth is calculated by an exponential power of 2 estimates of the root node