Expand description
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 likepar_splitandpar_windows, as well as various parallel sorting operations. See theParallelSlicetrait for the full list. - Strings (
&str) offer methods likepar_splitandpar_lines. See theParallelStringtrait 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 usecollect()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.)
Modules
Traits and functions used to implement parallel iteration. These are
low-level details – users of parallel iterators should not need to
interact with them directly. See the
plumbing README for a general overview.Structs
Chain is an iterator that joins b after a in one continuous iterator.
This struct is created by the chain() method on ParallelIteratorChunks is an iterator that groups elements of an underlying iterator.Cloned is an iterator that clones the elements of an underlying iterator.Copied is an iterator that copies the elements of an underlying iterator.Iterator adaptor for the
empty() function.Enumerate is an iterator that returns the current count along with the element.
This struct is created by the enumerate() method on IndexedParallelIteratorExponentialBlocks is a parallel iterator that consumes itself as a sequence
of parallel blocks of increasing sizes (exponentially).Filter takes a predicate filter_op and filters out elements that match.
This struct is created by the filter() method on ParallelIteratorFilterMap creates an iterator that uses filter_op to both filter and map elements.
This struct is created by the filter_map() method on ParallelIterator.FlatMap maps each element to a parallel iterator, then flattens these iterators together.
This struct is created by the flat_map() method on ParallelIteratorFlatMapIter maps each element to a serial iterator, then flattens these iterators together.
This struct is created by the flat_map_iter() method on ParallelIteratorFlatten turns each element to a parallel iterator, then flattens these iterators
together. This struct is created by the flatten() method on ParallelIterator.FlattenIter turns each element to a serial iterator, then flattens these iterators
together. This struct is created by the flatten_iter() method on ParallelIterator.Fold is an iterator that applies a function over an iterator producing a single value.
This struct is created by the fold() method on ParallelIteratorFoldChunks is an iterator that groups elements of an underlying iterator and applies a
function over them, producing a single value for each group.FoldChunksWith is an iterator that groups elements of an underlying iterator and applies a
function over them, producing a single value for each group.FoldWith is an iterator that applies a function over an iterator producing a single value.
This struct is created by the fold_with() method on ParallelIteratorInspect is an iterator that calls a function with a reference to each
element before yielding it.Interleave is an iterator that interleaves elements of iterators
i and j in one continuous iterator. This struct is created by
the interleave() method on IndexedParallelIteratorInterleaveShortest is an iterator that works similarly to
Interleave, but this version stops returning elements once one
of the iterators run out.Intersperse is an iterator that inserts a particular item between each
item of the adapted iterator. This struct is created by the
intersperse() method on ParallelIteratorIterBridge is a parallel iterator that wraps a sequential iterator.Map is an iterator that transforms the elements of an underlying iterator.MapInit is an iterator that transforms the elements of an underlying iterator.MapWith is an iterator that transforms the elements of an underlying iterator.MaxLen is an iterator that imposes a maximum length on iterator splits.
This struct is created by the with_max_len() method on IndexedParallelIteratorMinLen is an iterator that imposes a minimum length on iterator splits.
This struct is created by the with_min_len() method on IndexedParallelIteratorMultiZip is an iterator that zips up a tuple of parallel iterators to
produce tuples of their items.Iterator adaptor for the
once() function.PanicFuse is an adaptor that wraps an iterator with a fuse in case
of panics, to halt all threads as soon as possible.Positions takes a predicate predicate and filters out elements that match,
yielding their indices.Iterator adaptor for the
repeat() function.Iterator adaptor for the
repeatn() function.Rev is an iterator that produces elements in reverse order. This struct
is created by the rev() method on IndexedParallelIteratorSkip is an iterator that skips over the first n elements.
This struct is created by the skip() method on IndexedParallelIteratorSkipAny is an iterator that skips over n elements from anywhere in I.
This struct is created by the skip_any() method on ParallelIteratorSkipAnyWhile is an iterator that skips over elements from anywhere in I
until the callback returns false.
This struct is created by the skip_any_while() method on ParallelIteratorSplit is a parallel iterator using arbitrary data and a splitting function.
This struct is created by the split() function.StepBy is an iterator that skips n elements between each yield, where n is the given step.
This struct is created by the step_by() method on IndexedParallelIteratorTake is an iterator that iterates over the first n elements.
This struct is created by the take() method on IndexedParallelIteratorTakeAny is an iterator that iterates over n elements from anywhere in I.
This struct is created by the take_any() method on ParallelIteratorTakeAnyWhile is an iterator that iterates over elements from anywhere in I
until the callback returns false.
This struct is created by the take_any_while() method on ParallelIteratorTryFold is an iterator that applies a function over an iterator producing a single value.
This struct is created by the try_fold() method on ParallelIteratorTryFoldWith is an iterator that applies a function over an iterator producing a single value.
This struct is created by the try_fold_with() method on ParallelIteratorUniformBlocks is a parallel iterator that consumes itself as a sequence
of parallel blocks of constant sizes.Update is an iterator that mutates the elements of an
underlying iterator before they are yielded.ParallelIterator for arbitrary tree-shaped patterns.
Returned by the
walk_tree() function.ParallelIterator for arbitrary tree-shaped patterns.
Returned by the
walk_tree_postfix() function.ParallelIterator for arbitrary tree-shaped patterns.
Returned by the
walk_tree_prefix() function.WhileSome is an iterator that yields the Some elements of an iterator,
halting as soon as any None is produced.Zip is an iterator that zips up a and b into a single iterator
of pairs. This struct is created by the zip() method on
IndexedParallelIteratorAn
IndexedParallelIterator that iterates over two parallel iterators of equal
length simultaneously.Enums
The enum
Either with variants Left and Right is a general purpose
sum type with two cases.Traits
FromParallelIterator implements the creation of a collection
from a ParallelIterator. By implementing
FromParallelIterator for a given type, you define how it will be
created from an iterator.An iterator that supports “random access” to its data, meaning
that you can split it at arbitrary indices and draw data from
those points.
IntoParallelIterator implements the conversion to a ParallelIterator.IntoParallelRefIterator implements the conversion to a
ParallelIterator, providing shared references to the data.IntoParallelRefMutIterator implements the conversion to a
ParallelIterator, providing mutable references to the data.Conversion trait to convert an
Iterator to a ParallelIterator.ParallelDrainFull creates a parallel iterator that moves all items
from a collection while retaining the original capacity.ParallelDrainRange creates a parallel iterator that moves a range of items
from a collection while retaining the original capacity.ParallelExtend extends an existing collection with items from a ParallelIterator.Parallel version of the standard iterator trait.
Functions
Creates a parallel iterator that produces nothing.
Creates a parallel iterator that produces an element exactly once.
Creates a parallel iterator that endlessly repeats
elt (by
cloning it). Note that this iterator has “infinite” length, so
typically you would want to use zip or take or some other
means to shorten it, or consider using
the repeatn() function instead.Creates a parallel iterator that produces
n repeats of elt
(by cloning it).The
split function takes arbitrary data and a closure that knows how to
split it, and turns this into a ParallelIterator.Create a tree like parallel iterator from an initial root node.
The
children_of function should take a node and iterate on all of its child nodes.
The best parallelization is obtained when the tree is balanced
but we should also be able to handle harder cases.Create a tree like postfix parallel iterator from an initial root node.
The
children_of function should take a node and iterate on all of its child nodes.
The best parallelization is obtained when the tree is balanced
but we should also be able to handle harder cases.Create a tree-like prefix parallel iterator from an initial root node.
The
children_of function should take a node and return an iterator over its child nodes.
The best parallelization is obtained when the tree is balanced
but we should also be able to handle harder cases.