Module iter

Traits for writing parallel programs using an iterator-style interface

You will rarely need to interact with this module directly unless you have need to name one of the iterator types.

Parallel iterators make it easy to write iterator-like chains that execute in parallel: typically all you have to do is convert the first .iter() (or iter_mut(), into_iter(), etc) method into par_iter() (or par_iter_mut(), into_par_iter(), etc). For example, to compute the sum of the squares of a sequence of integers, one might write:

use rayon::prelude::*;
fn sum_of_squares(input: &[i32]) -> i32 {
    input.par_iter()
         .map(|i| i * i)
         .sum()
}

Or, to increment all the integers in a slice, you could write:

use rayon::prelude::*;
fn increment_all(input: &mut [i32]) {
    input.par_iter_mut()
         .for_each(|p| *p += 1);
}

To use parallel iterators, first import the traits by adding something like use rayon::prelude::* to your module. You can then call par_iter, par_iter_mut, or into_par_iter to get a parallel iterator. Like a regular iterator, parallel iterators work by first constructing a computation and then executing it.

In addition to par_iter() and friends, some types offer other ways to create (or consume) parallel iterators:

• Slices (&[T], &mut [T]) offer methods like par_split and par_windows, as well as various parallel sorting operations. See the ParallelSlice trait for the full list.
• Strings (&str) offer methods like par_split and par_lines. See the ParallelString trait for the full list.
• Various collections offer par_extend, which grows a collection given a parallel iterator. (If you don't have a collection to extend, you can use collect() to create a new one from scratch.)

To see the full range of methods available on parallel iterators, check out the ParallelIterator and IndexedParallelIterator traits.

If you'd like to build a custom parallel iterator, or to write your own combinator, then check out the split function and the plumbing module.

Note: Several of the ParallelIterator methods rely on a Try trait which has been deliberately obscured from the public API. This trait is intended to mirror the unstable std::ops::Try with implementations for Option and Result, where Some/Ok values will let those iterators continue, but None/Err values will exit early.

A note about object safety: It is currently not possible to wrap a ParallelIterator (or any trait that depends on it) using a Box<dyn ParallelIterator> or other kind of dynamic allocation, because ParallelIterator is not object-safe. (This keeps the implementation simpler and allows extra optimizations.)