Skip to main content

ParallelIteratorExt

Trait ParallelIteratorExt 

Source
pub trait ParallelIteratorExt: ParallelIterator {
Show 43 methods // Provided methods fn all<F>(self, f: F) -> bool where F: Fn(Self::Item) -> bool + Sync { ... } fn any<F>(self, f: F) -> bool where F: Fn(Self::Item) -> bool + Sync { ... } fn cmp<T>(self) -> Ordering where Self: ParallelIterator<Item = (T, T)>, T: Ord { ... } fn cmp_by<T, U, F>(self, f: F) -> Ordering where Self: ParallelIterator<Item = (T, U)>, F: Fn(T, U) -> Ordering + Sync { ... } fn cmp_by_key<T, A, F>(self, f: F) -> Ordering where Self: ParallelIterator<Item = (T, T)>, F: Fn(T) -> A + Sync, A: Ord { ... } fn cmp_by_keys<T, U, A, F, G>(self, f: F, g: G) -> Ordering where Self: ParallelIterator<Item = (T, U)>, F: Fn(T) -> A + Sync, G: Fn(U) -> A + Sync, A: Ord { ... } fn collect_per_thread<C>(self) -> Vec<C> where C: FromIterator<Self::Item> + Send { ... } fn eq<T, U>(self) -> bool where Self: ParallelIterator<Item = (T, U)>, T: PartialEq<U> { ... } fn eq_by_key<T, A, F>(self, f: F) -> bool where Self: ParallelIterator<Item = (T, T)>, F: Fn(T) -> A + Sync, A: PartialEq { ... } fn eq_by_keys<T, U, A, B, F, G>(self, f: F, g: G) -> bool where Self: ParallelIterator<Item = (T, U)>, F: Fn(T) -> A + Sync, G: Fn(U) -> B + Sync, A: PartialEq<B> { ... } fn find_any<F>(self, f: F) -> Option<Self::Item> where F: Fn(&Self::Item) -> bool + Sync, Self::Item: Send { ... } fn find_first<F>(self, f: F) -> Option<Self::Item> where F: Fn(&Self::Item) -> bool + Sync, Self::Item: Send { ... } fn find_map_any<T, F>(self, f: F) -> Option<T> where F: Fn(Self::Item) -> Option<T> + Sync, T: Send { ... } fn find_map_first<T, F>(self, f: F) -> Option<T> where F: Fn(Self::Item) -> Option<T> + Sync, T: Send { ... } fn fold_per_thread<T, U, InitPerThread, FoldPerThread, InitFinal, FoldFinal>( self, init_per_thread: InitPerThread, fold_per_thread: FoldPerThread, init_final: InitFinal, fold_final: FoldFinal, ) -> U where InitPerThread: Fn() -> T + Sync, FoldPerThread: Fn(T, Self::Item) -> T + Sync, InitFinal: Fn(usize) -> U, FoldFinal: Fn(U, T) -> U, T: Send { ... } fn for_each<F>(self, f: F) where F: Fn(Self::Item) + Sync { ... } fn for_each_init<T, Init, F>(self, init: Init, f: F) where Init: Fn() -> T + Sync, F: Fn(&mut T, Self::Item) + Sync { ... } fn map<T, F>(self, f: F) -> Map<Self, F> where F: Fn(Self::Item) -> T + Sync { ... } fn max(self) -> Option<Self::Item> where Self::Item: Ord + Send { ... } fn max_by<F>(self, f: F) -> Option<Self::Item> where F: Fn(&Self::Item, &Self::Item) -> Ordering + Sync, Self::Item: Send { ... } fn max_by_key<T, F>(self, f: F) -> Option<Self::Item> where F: Fn(&Self::Item) -> T + Sync, T: Ord + Send, Self::Item: Send { ... } fn min(self) -> Option<Self::Item> where Self::Item: Ord + Send { ... } fn min_by<F>(self, f: F) -> Option<Self::Item> where F: Fn(&Self::Item, &Self::Item) -> Ordering + Sync, Self::Item: Send { ... } fn min_by_key<T, F>(self, f: F) -> Option<Self::Item> where F: Fn(&Self::Item) -> T + Sync, T: Ord + Send, Self::Item: Send { ... } fn minmax(self) -> MinMaxResult<Self::Item> where Self::Item: Ord + Send { ... } fn minmax_by<F>(self, f: F) -> MinMaxResult<Self::Item> where F: Fn(&Self::Item, &Self::Item) -> Ordering + Sync, Self::Item: Send { ... } fn minmax_by_key<T, F>(self, f: F) -> MinMaxResult<Self::Item> where F: Fn(&Self::Item) -> T + Sync, T: Ord + Send, Self::Item: Send { ... } fn ne<T, U>(self) -> bool where Self: ParallelIterator<Item = (T, U)>, T: PartialEq<U> { ... } fn ne_by_key<T, A, F>(self, f: F) -> bool where Self: ParallelIterator<Item = (T, T)>, F: Fn(T) -> A + Sync, A: PartialEq { ... } fn ne_by_keys<T, U, A, B, F, G>(self, f: F, g: G) -> bool where Self: ParallelIterator<Item = (T, U)>, F: Fn(T) -> A + Sync, G: Fn(U) -> B + Sync, A: PartialEq<B> { ... } fn panic_fuse(self) -> PanicFuse<Self> { ... } fn partial_cmp<T, U>(self) -> Option<Ordering> where Self: ParallelIterator<Item = (T, U)>, T: PartialOrd<U> { ... } fn partial_cmp_by<T, U, F>(self, f: F) -> Option<Ordering> where Self: ParallelIterator<Item = (T, U)>, F: Fn(T, U) -> Option<Ordering> + Sync { ... } fn partial_cmp_by_key<T, A, F>(self, f: F) -> Option<Ordering> where Self: ParallelIterator<Item = (T, T)>, F: Fn(T) -> A + Sync, A: PartialOrd { ... } fn partial_cmp_by_keys<T, U, A, B, F, G>( self, f: F, g: G, ) -> Option<Ordering> where Self: ParallelIterator<Item = (T, U)>, F: Fn(T) -> A + Sync, G: Fn(U) -> B + Sync, A: PartialOrd<B> { ... } fn product<T>(self) -> T where T: Product<Self::Item> + Product<T> + Send { ... } fn reduce<Init, F>(self, init: Init, f: F) -> Self::Item where Init: Fn() -> Self::Item + Sync, F: Fn(Self::Item, Self::Item) -> Self::Item + Sync, Self::Item: Send { ... } fn sum<T>(self) -> T where T: Sum<Self::Item> + Sum<T> + Send { ... } fn try_collect_per_thread<C>( self, ) -> <<Self::Item as Try>::Residual as Residual<Vec<C>>>::TryType where Self::Item: Try, <Self::Item as Try>::Residual: Residual<C> + Residual<Vec<C>>, C: FromIterator<<Self::Item as Try>::Output> + Send, <<Self::Item as Try>::Residual as Residual<C>>::TryType: Send { ... } fn try_fold_per_thread<T, U, R, S, InitPerThread, TryFoldPerThread, InitFinal, TryFoldFinal>( self, init_per_thread: InitPerThread, try_fold_per_thread: TryFoldPerThread, init_final: InitFinal, try_fold_final: TryFoldFinal, ) -> S where InitPerThread: Fn() -> T + Sync, TryFoldPerThread: Fn(T, Self::Item) -> R + Sync, InitFinal: Fn(usize) -> U, TryFoldFinal: Fn(U, R) -> S, R: Try<Output = T> + Send, S: Try<Output = U> { ... } fn try_for_each<R, F>(self, f: F) -> R where F: Fn(Self::Item) -> R + Sync, R: Try<Output = ()> + Send { ... } fn try_for_each_init<T, Init, R, F>(self, init: Init, f: F) -> R where Init: Fn() -> T + Sync, F: Fn(&mut T, Self::Item) -> R + Sync, R: Try<Output = ()> + Send { ... } fn try_reduce<R, Init, F>(self, init: Init, f: F) -> R where Init: Fn() -> Self::Item + Sync, F: Fn(Self::Item, Self::Item) -> R + Sync, R: Try<Output = Self::Item> + Send { ... }
}
Expand description

Additional methods provided for types that implement ParallelIterator.

See also ParallelSourceExt for more adaptors that only apply to parallel sources (earlier in the pipeline).

Provided Methods§

Source

fn all<F>(self, f: F) -> bool
where F: Fn(Self::Item) -> bool + Sync,

Returns true if all items produced by this iterator satisfy the predicate f, and false otherwise.

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

let all_even = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .all(|&x| x % 2 == 0);
assert!(!all_even);

let all_positive = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .all(|&x| x > 0);
assert!(all_positive);

This returns true if the iterator is empty.

let input: [i32; 0] = [];

let all_empty = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .all(|_| false);
assert!(all_empty);
Source

fn any<F>(self, f: F) -> bool
where F: Fn(Self::Item) -> bool + Sync,

Returns true if any item produced by this iterator satisfies the predicate f, and false otherwise.

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

let any_even = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .any(|&x| x % 2 == 0);
assert!(any_even);

let any_zero = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .any(|&x| x == 0);
assert!(!any_zero);

This returns false if the iterator is empty.

let input: [i32; 0] = [];

let any_empty = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .any(|_| true);
assert!(!any_empty);
Source

fn cmp<T>(self) -> Ordering
where Self: ParallelIterator<Item = (T, T)>, T: Ord,

Compare the pairs of items produced by this iterator using lexicographic order.

See also cmp_by(), cmp_by_key() and cmp_by_keys() to use custom comparison functions, and partial_cmp() and its variants if the items only implement PartialOrd.

If you only care about equality, eq(), ne() and their variants are more efficient.

let lhs = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let rhs = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let ordering = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .cmp();
assert_eq!(ordering, Ordering::Equal);
let lhs = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let rhs = [10, 1, 2, 3, 4, 5, 6, 7, 8, 9];
let ordering = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .cmp();
assert_eq!(ordering, Ordering::Less);
let lhs = [10, 1, 2, 3, 4, 5, 6, 7, 8, 9];
let rhs = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let ordering = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .cmp();
assert_eq!(ordering, Ordering::Greater);

This returns Ordering::Equal if the iterator is empty.

let pairs: [(i32, i32); 0] = [];
let ordering = pairs
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .cmp();
assert_eq!(ordering, Ordering::Equal);
Source

fn cmp_by<T, U, F>(self, f: F) -> Ordering
where Self: ParallelIterator<Item = (T, U)>, F: Fn(T, U) -> Ordering + Sync,

Compare the pairs of items produced by this iterator using lexicographic order with the comparison function f.

See also the other comparison adaptors such as cmp() or partial_cmp_by().

/// Compare every other item of the given slices.
fn compare_even_indices(&lhs: &&[i32], &rhs: &&[i32]) -> Ordering {
    lhs.iter().step_by(2).cmp(rhs.iter().step_by(2))
}

let lhs: [&[_]; 5] = [&[1, 1], &[2, 2], &[3, 3], &[4, 4], &[5, 5]];
let rhs: [&[_]; 5] = [&[1, 6], &[2, 7], &[3, 8], &[4, 9], &[5, 10]];
let ordering = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .cmp_by(compare_even_indices);
// The comparison is [Equal, Equal, Equal, Equal, Equal] -> Equal
assert_eq!(ordering, Ordering::Equal);

let lhs: [&[_]; 5] = [&[1, 1, 1], &[2, 2, 3], &[4, 3], &[4, 4, 5], &[5, 5, 6]];
let rhs: [&[_]; 5] = [&[1, 6, 2], &[2, 7], &[3, 8, 3], &[4, 9, 4], &[5, 10, 5]];
let ordering = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .cmp_by(compare_even_indices);
// The comparison is [Less, Greater, Greater, Greater, Greater] -> Less
assert_eq!(ordering, Ordering::Less);
Source

fn cmp_by_key<T, A, F>(self, f: F) -> Ordering
where Self: ParallelIterator<Item = (T, T)>, F: Fn(T) -> A + Sync, A: Ord,

Compare the pairs of items produced by this iterator using lexicographic order, after mapping them with f.

See also the other comparison adaptors such as cmp_by_keys(), partial_cmp_by_key() or eq_by_key().

let lhs = [
    (1, "Lorem"),
    (2, "ipsum"),
    (3, "dolor"),
    (4, "sit"),
    (5, "amet"),
];
let rhs = [
    (5, "Lorem"),
    (1, "ipsum"),
    (2, "dolor"),
    (3, "sit"),
    (4, "amet"),
];
let ordering = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .cmp_by_key(|x| x.0);
assert_eq!(ordering, Ordering::Less);
Source

fn cmp_by_keys<T, U, A, F, G>(self, f: F, g: G) -> Ordering
where Self: ParallelIterator<Item = (T, U)>, F: Fn(T) -> A + Sync, G: Fn(U) -> A + Sync, A: Ord,

Compare the pairs of items produced by this iterator using lexicographic order, after mapping them with f and g.

See also the other comparison adaptors such as cmp_by_key(), partial_cmp_by_keys() or eq_by_keys().

let lhs = [(1, 1.0), (2, 2.0), (3, 3.0), (4, 4.0), (5, 5.0)];
let rhs = [
    (5, "Lorem"),
    (1, "ipsum"),
    (2, "dolor"),
    (3, "sit"),
    (4, "amet"),
];
let ordering = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .cmp_by_keys(|x| x.0, |y| y.0);
assert_eq!(ordering, Ordering::Less);
Source

fn collect_per_thread<C>(self) -> Vec<C>
where C: FromIterator<Self::Item> + Send,

Collect items from this iterator into a per-thread collection of type C, then aggregates these into a Vec<C> without further flattening.

See also try_collect_per_thread() and fold_per_thread().

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let collection: Vec<Vec<i32>> = input
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .collect_per_thread();

let mut values: Vec<i32> = collection.into_iter().flatten().collect();
values.sort_unstable();
assert_eq!(values, &[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);

The outer type of the result is currently always Vec, but the inner type can be anything that implements FromIterator.

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let collection: Vec<HashSet<i32>> = input
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .collect_per_thread();

let mut values: Vec<i32> = collection.into_iter().flatten().collect();
values.sort_unstable();
assert_eq!(values, &[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
Source

fn eq<T, U>(self) -> bool
where Self: ParallelIterator<Item = (T, U)>, T: PartialEq<U>,

Returns true if all pairs of items produced by this iterator are equal, and false otherwise.

This returns the opposite of ne().

See also eq_by_key() and eq_by_keys() to use custom comparison functions, or the more general all() and any().

let lhs = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let rhs = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let equal = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .eq();
assert!(equal);
let lhs = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let rhs = [1, 2, 3, 42, 5, 6, 7, 8, 9, 10];
let equal = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .eq();
assert!(!equal);

The underlying items only need to implement PartialEq, full equality with Eq isn’t required.

let lhs = [1.0, f64::NAN];
let rhs = [1.0, f64::NAN];
let equal = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .eq();
assert!(!equal);

The underlying items don’t need to be of the same type, as long as they implement PartialEq with each other.

let lhs: &[[i32; 2]] = &[[1, 2], [3, 4], [5, 6], [7, 8], [9, 10]];
let rhs: &[&[i32]] = &[&[1, 2], &[3, 4], &[5, 6], &[7, 8], &[9, 10]];
let equal = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .eq();
assert!(equal);

This returns true if the iterator is empty.

let pairs: [(i32, i32); 0] = [];
let eq_empty = pairs
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .eq();
assert!(eq_empty);
Source

fn eq_by_key<T, A, F>(self, f: F) -> bool
where Self: ParallelIterator<Item = (T, T)>, F: Fn(T) -> A + Sync, A: PartialEq,

Returns true if all pairs of items produced by this iterator yield equal keys when mapped by f, and false otherwise.

This returns the opposite of ne_by_key().

let lhs = [(1, 1.0), (2, 2.0), (3, 3.0), (4, 4.0), (5, 5.0)];
let rhs = [(1, 6.0), (2, 7.0), (3, 8.0), (4, 9.0), (5, 10.0)];
let equal = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .eq_by_key(|x| x.0);
assert!(equal);

See also:

  • eq() for the simplest equality adaptor over PartialEq types,
  • eq_by_keys() if the left-hand and right-hand sides are of different types or have different key extraction functions,
  • all() and any() for more general adaptors.
Source

fn eq_by_keys<T, U, A, B, F, G>(self, f: F, g: G) -> bool
where Self: ParallelIterator<Item = (T, U)>, F: Fn(T) -> A + Sync, G: Fn(U) -> B + Sync, A: PartialEq<B>,

Returns true if all pairs of items produced by this iterator yield equal keys when mapped by f and g, and false otherwise.

This returns the opposite of ne_by_keys().

let lhs = [(1, 1.0), (2, 2.0), (3, 3.0), (4, 4.0), (5, 5.0)];
let rhs = [
    (1, "Lorem"),
    (2, "ipsum"),
    (3, "dolor"),
    (4, "sit"),
    (5, "amet"),
];
let equal = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .eq_by_keys(|x| x.0, |y| y.0);
assert!(equal);

See also:

  • eq() for the simplest equality adaptor over PartialEq types,
  • eq_by_key() if the left-hand and right-hand key extraction functions are the same and on the same types,
  • all() and any() for more general adaptors.
Source

fn find_any<F>(self, f: F) -> Option<Self::Item>
where F: Fn(&Self::Item) -> bool + Sync, Self::Item: Send,

Returns any item that satisfies the predicate f, or None if no item satisfies it.

If multiple items satisfy f, an arbitrary one is returned.

See also find_map_any(), useful if the Item type isn’t Send.

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

let four = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .find_any(|&&x| x == 4);
assert_eq!(four, Some(&4));

let twenty = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .find_any(|&&x| x == 20);
assert_eq!(twenty, None);

let any_even = input
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .find_any(|&x| x % 2 == 0);
assert!(any_even.unwrap() % 2 == 0);
Source

fn find_first<F>(self, f: F) -> Option<Self::Item>
where F: Fn(&Self::Item) -> bool + Sync, Self::Item: Send,

Returns the first item that satisfies the predicate f, or None if no item satisfies it.

See also find_map_first(), useful if the Item type isn’t Send.

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];

let four = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .find_first(|&&x| x == 4);
assert_eq!(four, Some(&4));

let twenty = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .find_first(|&&x| x == 20);
assert_eq!(twenty, None);

let first_even = input
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .find_first(|&x| x % 2 == 0);
assert_eq!(first_even, Some(2));
Source

fn find_map_any<T, F>(self, f: F) -> Option<T>
where F: Fn(Self::Item) -> Option<T> + Sync, T: Send,

Applies the function f to items of this iterator, returning any non-None result.

If multiple items map to Some(_) result, an arbitrary one is returned.

Contrary to find_any(), the Item type doesn’t need to be Send, only the result type.

let input = [
    "Lorem",
    "ipsum",
    "dolor",
    "sit",
    "amet",
    "consectetur",
    "adipiscing",
    "elit",
    "sed",
    "do",
];

let four_bytes_word = input
    .par_iter()
    .enumerate()
    .with_thread_pool(&mut thread_pool)
    .find_map_any(|(i, x)| if x.len() == 4 { Some(i) } else { None });

assert!(four_bytes_word.is_some());
let four_bytes_word = four_bytes_word.unwrap();
assert!(four_bytes_word == 4 || four_bytes_word == 7);
assert_eq!(input[four_bytes_word].len(), 4);
Source

fn find_map_first<T, F>(self, f: F) -> Option<T>
where F: Fn(Self::Item) -> Option<T> + Sync, T: Send,

Applies the function f to items of this iterator, returning the first non-None result.

Contrary to find_first(), the Item type doesn’t need to be Send, only the result type.

let input = [
    "Lorem",
    "ipsum",
    "dolor",
    "sit",
    "amet",
    "consectetur",
    "adipiscing",
    "elit",
    "sed",
    "do",
];

let four_bytes_word = input
    .par_iter()
    .enumerate()
    .with_thread_pool(&mut thread_pool)
    .find_map_first(|(i, x)| if x.len() == 4 { Some(i) } else { None });

// Position of "amet" in the input array.
assert_eq!(four_bytes_word, Some(4));
Source

fn fold_per_thread<T, U, InitPerThread, FoldPerThread, InitFinal, FoldFinal>( self, init_per_thread: InitPerThread, fold_per_thread: FoldPerThread, init_final: InitFinal, fold_final: FoldFinal, ) -> U
where InitPerThread: Fn() -> T + Sync, FoldPerThread: Fn(T, Self::Item) -> T + Sync, InitFinal: Fn(usize) -> U, FoldFinal: Fn(U, T) -> U, T: Send,

Folds items of this parallel iterator into a per-thread accumulator of type T, then folds again the per-thread results into an output of type U.

Per-thread accumulation is done with the init_per_thread and fold_per_thread functions, and final accumulation with the init_final and fold_final functions. The init_final function receives the number of threads as input. The Item and U types can be non-Send: only the per-thread accumulator type T needs to be Send.

See also try_fold_per_thread() and collect_per_thread().

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let collection: Vec<Vec<i32>> = input
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .fold_per_thread(
        Vec::new,
        |mut vec, x| {
            vec.push(x);
            vec
        },
        Vec::with_capacity,
        |mut vecvec, vec| {
            vecvec.push(vec);
            vecvec
        },
    );

let mut values: Vec<i32> = collection.into_iter().flatten().collect();
values.sort_unstable();
assert_eq!(values, &[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]);
Source

fn for_each<F>(self, f: F)
where F: Fn(Self::Item) + Sync,

Runs f on each item of this parallel iterator.

See also for_each_init() if you need to initialize a per-thread value and pass it together with each item.

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let set = Mutex::new(HashSet::new());
input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .for_each(|&x| {
        set.lock().unwrap().insert(x);
    });
assert_eq!(set.into_inner().unwrap(), (1..=10).collect());
Source

fn for_each_init<T, Init, F>(self, init: Init, f: F)
where Init: Fn() -> T + Sync, F: Fn(&mut T, Self::Item) + Sync,

Runs f on each item of this iterator, together with a per-thread mutable value returned by init.

The init function will be called only once per worker thread. The companion value returned by init doesn’t need to be Send nor Sync.

use rand::RngExt;

let mut bits: [bool; 128] = [true; 128];
bits.par_iter_mut()
    .with_thread_pool(&mut thread_pool)
    .for_each_init(
        rand::rng, // A thread-local RNG that is neither Send nor Sync.
        |rng, bit| {
            if rng.random() {
                *bit = false;
            }
        },
    );

// The probability that these checks fail is negligible.
assert!(bits.iter().any(|&x| x));
assert!(bits.iter().any(|&x| !x));
Source

fn map<T, F>(self, f: F) -> Map<Self, F>
where F: Fn(Self::Item) -> T + Sync,

Applies the function f to each item of this iterator, returning a parallel iterator producing the mapped items.

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let double_sum = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .map(|&x| x * 2)
    .sum::<i32>();
assert_eq!(double_sum, 10 * 11);

Mapping to a non-Send non-Sync type such as Rc is fine.

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let sum = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .map(|&x| Rc::new(x))
    .pipeline(|| 0, |acc, x| acc + *x, |acc| acc, |a, b| a + b);
assert_eq!(sum, 5 * 11);
Source

fn max(self) -> Option<Self::Item>
where Self::Item: Ord + Send,

Returns the maximal item of this iterator, or None if this iterator is empty.

If there are several maximal items, an arbitrary one is returned.

See also minmax().

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let max = input.par_iter().with_thread_pool(&mut thread_pool).max();
assert_eq!(max, Some(&10));
Source

fn max_by<F>(self, f: F) -> Option<Self::Item>
where F: Fn(&Self::Item, &Self::Item) -> Ordering + Sync, Self::Item: Send,

Returns the maximal item of this iterator according to the comparison function f, or None if this iterator is empty.

If there are several maximal items, an arbitrary one is returned.

See also minmax_by().

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let max = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    // Custom comparison function where even numbers are smaller than all odd numbers.
    .max_by(|x, y| (*x % 2).cmp(&(*y % 2)).then(x.cmp(y)));
assert_eq!(max, Some(&9));
Source

fn max_by_key<T, F>(self, f: F) -> Option<Self::Item>
where F: Fn(&Self::Item) -> T + Sync, T: Ord + Send, Self::Item: Send,

Returns the maximal item of this iterator according to the keys derived from the mapping function f, or None if this iterator is empty.

If there are several maximal items, an arbitrary one is returned.

See also minmax_by_key().

let input = ["ccc", "aaaaa", "dd", "e", "bbbb"];

let max = input.par_iter().with_thread_pool(&mut thread_pool).max();
assert_eq!(max, Some(&"e"));

let max_by_len = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .max_by_key(|x| x.len());
assert_eq!(max_by_len, Some(&"aaaaa"));
Source

fn min(self) -> Option<Self::Item>
where Self::Item: Ord + Send,

Returns the minimal item of this iterator, or None if this iterator is empty.

If there are several minimal items, an arbitrary one is returned.

See also minmax().

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let min = input.par_iter().with_thread_pool(&mut thread_pool).min();
assert_eq!(min, Some(&1));
Source

fn min_by<F>(self, f: F) -> Option<Self::Item>
where F: Fn(&Self::Item, &Self::Item) -> Ordering + Sync, Self::Item: Send,

Returns the minimal item of this iterator according to the comparison function f, or None if this iterator is empty.

If there are several minimal items, an arbitrary one is returned.

See also minmax_by().

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let min = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    // Custom comparison function where even numbers are smaller than all odd numbers.
    .min_by(|x, y| (*x % 2).cmp(&(*y % 2)).then(x.cmp(y)));
assert_eq!(min, Some(&2));
Source

fn min_by_key<T, F>(self, f: F) -> Option<Self::Item>
where F: Fn(&Self::Item) -> T + Sync, T: Ord + Send, Self::Item: Send,

Returns the minimal item of this iterator according to the keys derived from the mapping function f, or None if this iterator is empty.

If there are several minimal items, an arbitrary one is returned.

See also minmax_by_key().

let input = ["ccc", "aaaaa", "dd", "e", "bbbb"];

let min = input.par_iter().with_thread_pool(&mut thread_pool).min();
assert_eq!(min, Some(&"aaaaa"));

let min_by_len = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .min_by_key(|x| x.len());
assert_eq!(min_by_len, Some(&"e"));
Source

fn minmax(self) -> MinMaxResult<Self::Item>
where Self::Item: Ord + Send,

Returns the minimal and maximal items of this iterator.

If there are several minimal and/or maximal items, arbirary ones are returned.

This performs only 1.5 * n comparisons for an iterator of length n, which is more efficient than calling min() and max() separately.

use paralight::iter::MinMaxResult;

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let minmax = input.par_iter().with_thread_pool(&mut thread_pool).minmax();
assert_eq!(minmax, MinMaxResult::MinMax { min: &1, max: &10 });

let input = [1];
let minmax = input.par_iter().with_thread_pool(&mut thread_pool).minmax();
assert_eq!(minmax, MinMaxResult::OneElement(&1));

let input: [i32; 0] = [];
let minmax = input.par_iter().with_thread_pool(&mut thread_pool).minmax();
assert_eq!(minmax, MinMaxResult::NoElements);
Source

fn minmax_by<F>(self, f: F) -> MinMaxResult<Self::Item>
where F: Fn(&Self::Item, &Self::Item) -> Ordering + Sync, Self::Item: Send,

Returns the minimal and maximal items of this iterator according to the comparison function f.

If there are several minimal and/or maximal items, arbirary ones are returned.

This performs only 1.5 * n comparisons for an iterator of length n, which is more efficient than calling min_by() and max_by() separately.

use paralight::iter::MinMaxResult;

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let minmax = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    // Custom comparison function where even numbers are smaller than all odd numbers.
    .minmax_by(|x, y| (*x % 2).cmp(&(*y % 2)).then(x.cmp(y)));
assert_eq!(minmax, MinMaxResult::MinMax { min: &2, max: &9 });
Source

fn minmax_by_key<T, F>(self, f: F) -> MinMaxResult<Self::Item>
where F: Fn(&Self::Item) -> T + Sync, T: Ord + Send, Self::Item: Send,

Returns the minimal and maximal items of this iterator according to the keys derived from the mapping function f.

If there are several minimal and/or maximal items, arbirary ones are returned.

This performs only 1.5 * n comparisons for an iterator of length n, which is more efficient than calling min_by_key() and max_by_key() separately.

use paralight::iter::MinMaxResult;

let input = ["ccc", "aaaaa", "dd", "e", "bbbb"];

let minmax = input.par_iter().with_thread_pool(&mut thread_pool).minmax();
assert_eq!(
    minmax,
    MinMaxResult::MinMax {
        min: &"aaaaa",
        max: &"e"
    }
);

let minmax_by_len = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .minmax_by_key(|x| x.len());
assert_eq!(
    minmax_by_len,
    MinMaxResult::MinMax {
        min: &"e",
        max: &"aaaaa"
    }
);
Source

fn ne<T, U>(self) -> bool
where Self: ParallelIterator<Item = (T, U)>, T: PartialEq<U>,

Returns true if any pair of items produced by this iterator consists of unequal items, and false otherwise.

This returns the opposite of eq().

See also ne_by_key() and ne_by_keys() to use custom comparison functions, or the more general all() and any().

let lhs = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let rhs = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let not_equal = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .ne();
assert!(!not_equal);
let lhs = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let rhs = [1, 2, 3, 42, 5, 6, 7, 8, 9, 10];
let not_equal = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .ne();
assert!(not_equal);

The underlying items only need to implement PartialEq, full equality with Eq isn’t required.

let lhs = [1.0, f64::NAN];
let rhs = [1.0, f64::NAN];
let not_equal = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .ne();
assert!(not_equal);

The underlying items don’t need to be of the same type, as long as they implement PartialEq with each other.

let lhs: &[[i32; 2]] = &[[1, 2], [3, 4], [5, 6], [7, 8], [9, 10]];
let rhs: &[&[i32]] = &[&[1, 2], &[3, 4], &[5, 6], &[7, 8], &[9, 10]];
let not_equal = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .ne();
assert!(!not_equal);

This returns false if the iterator is empty.

let pairs: [(i32, i32); 0] = [];
let ne_empty = pairs
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .ne();
assert!(!ne_empty);
Source

fn ne_by_key<T, A, F>(self, f: F) -> bool
where Self: ParallelIterator<Item = (T, T)>, F: Fn(T) -> A + Sync, A: PartialEq,

Returns true if any pair of items produced by this iterator yields unequal keys when mapped by f, and false otherwise.

This returns the opposite of eq_by_key().

let lhs = [(1, 1.0), (2, 2.0), (3, 3.0), (4, 4.0), (5, 5.0)];
let rhs = [(1, 6.0), (2, 7.0), (3, 8.0), (4, 9.0), (5, 10.0)];
let not_equal = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .ne_by_key(|x| x.0);
assert!(!not_equal);

See also:

  • ne() for the simplest equality adaptor over PartialEq types,
  • ne_by_keys() if the left-hand and right-hand sides are of different types or have different key extraction functions,
  • all() and any() for more general adaptors.
Source

fn ne_by_keys<T, U, A, B, F, G>(self, f: F, g: G) -> bool
where Self: ParallelIterator<Item = (T, U)>, F: Fn(T) -> A + Sync, G: Fn(U) -> B + Sync, A: PartialEq<B>,

Returns true if any pair of items produced by this iterator yields unequal keys when mapped by f and g, and false otherwise.

This returns the opposite of eq_by_keys().

let lhs = [(1, 1.0), (2, 2.0), (3, 3.0), (4, 4.0), (5, 5.0)];
let rhs = [
    (1, "Lorem"),
    (2, "ipsum"),
    (3, "dolor"),
    (4, "sit"),
    (5, "amet"),
];
let not_equal = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .ne_by_keys(|x| x.0, |y| y.0);
assert!(!not_equal);

See also:

  • ne() for the simplest equality adaptor over PartialEq types,
  • ne_by_key() if the left-hand and right-hand key extraction functions are the same and on the same types,
  • all() and any() for more general adaptors.
Source

fn panic_fuse(self) -> PanicFuse<Self>

Attaches a fuse to this iterator that triggers in case of panics, to interrupt the other threads as soon as possible.

Without this adaptor, a panic in a worker thread is eventually propagated to the caller, but only after all other threads have finished processing their items. Indeed, a panic normally doesn’t interrupt other threads (unless the program is compiled in panic="abort" mode).

With this adaptor, a communication layer indicates if a panic happened: worker threads check it before processing each item. This comes at the cost of additional synchronization overhead, and may also prevent some optimizations.

ⓘ
use std::thread::sleep;
use std::time::Duration;

(0..1_000_000)
    .into_par_iter()
    .with_thread_pool(&mut thread_pool)
    .panic_fuse()
    .for_each(|i| {
        sleep(Duration::from_secs(1));
        assert!(i > 0);
        println!("item: {i}");
    });

This fuse applies to panics caused anywhere in the iterator pipeline.

ⓘ
use std::thread::sleep;
use std::time::Duration;

(0..1_000_000)
    .into_par_iter()
    .inspect(|&i| {
        sleep(Duration::from_secs(1));
        assert!(i > 0);
    })
    .with_thread_pool(&mut thread_pool)
    .panic_fuse()
    .for_each(|i| println!("item: {i}"));
Source

fn partial_cmp<T, U>(self) -> Option<Ordering>
where Self: ParallelIterator<Item = (T, U)>, T: PartialOrd<U>,

Compare the pairs of items produced by this iterator using lexicographic order.

See also partial_cmp_by(), partial_cmp_by_key() and partial_cmp_by_keys() to use custom comparison functions, and cmp() and its variants if the items implement Ord.

If you only care about equality, eq(), ne() and their variants are more efficient.

let lhs = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0];
let rhs = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0];
let ordering = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .partial_cmp();
assert_eq!(ordering, Some(Ordering::Equal));
let lhs = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, 10.0];
let rhs = [10.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0];
let ordering = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .partial_cmp();
assert_eq!(ordering, Some(Ordering::Less));
let lhs = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, f64::NAN];
let rhs = [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0, f64::NAN];
let ordering = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .partial_cmp();
assert_eq!(ordering, None);
let lhs = [2.0, f64::NAN, f64::NAN, f64::NAN, f64::NAN, f64::NAN];
let rhs = [1.0, f64::NAN, f64::NAN, f64::NAN, f64::NAN, f64::NAN];
let ordering = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .partial_cmp();
assert_eq!(ordering, Some(Ordering::Greater));

This returns Some(Ordering::Equal) if the iterator is empty.

let pairs: [(f64, f64); 0] = [];
let ordering = pairs
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .partial_cmp();
assert_eq!(ordering, Some(Ordering::Equal));
Source

fn partial_cmp_by<T, U, F>(self, f: F) -> Option<Ordering>
where Self: ParallelIterator<Item = (T, U)>, F: Fn(T, U) -> Option<Ordering> + Sync,

Compare the pairs of items produced by this iterator using lexicographic order with the comparison function f.

See also the other comparison adaptors such as partial_cmp() or cmp_by().

/// Compare if one set is a subset of the other. Inputs must be sorted.
fn compare_sets(&lhs: &&[i32], &rhs: &&[i32]) -> Option<Ordering> {
    match (is_subset(lhs, rhs), is_subset(rhs, lhs)) {
        (false, false) => None,
        (true, false) => Some(Ordering::Less),
        (false, true) => Some(Ordering::Greater),
        (true, true) => Some(Ordering::Equal),
    }
}

/// Returns true if the first argument is a subset of the second. Inputs must be sorted.
fn is_subset(lhs: &[i32], rhs: &[i32]) -> bool {
    /* Implementation details omitted */
}

let lhs: [&[_]; 5] = [&[1], &[2], &[3], &[4], &[5]];
let rhs: [&[_]; 5] = [&[1], &[2], &[3], &[4], &[5]];
let ordering = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .partial_cmp_by(compare_sets);
// The comparison is [Equal, Equal, Equal, Equal, Equal] -> Equal
assert_eq!(ordering, Some(Ordering::Equal));

let lhs: [&[_]; 5] = [&[1], &[2, 7], &[3], &[4], &[5]];
let rhs: [&[_]; 5] = [&[1, 6], &[2], &[8], &[9], &[10]];
let ordering = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .partial_cmp_by(compare_sets);
// The comparison is [Less, Greater, None, None, None] -> Less
assert_eq!(ordering, Some(Ordering::Less));

let lhs: [&[_]; 5] = [&[1], &[2], &[3], &[4], &[5]];
let rhs: [&[_]; 5] = [&[6], &[2], &[3], &[4], &[5]];
let ordering = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .partial_cmp_by(compare_sets);
// The comparison is [None, Equal, Equal, Equal, Equal] -> None
assert_eq!(ordering, None);
Source

fn partial_cmp_by_key<T, A, F>(self, f: F) -> Option<Ordering>
where Self: ParallelIterator<Item = (T, T)>, F: Fn(T) -> A + Sync, A: PartialOrd,

Compare the pairs of items produced by this iterator using lexicographic order, after mapping them with f.

See also the other comparison adaptors such as partial_cmp_by_keys(), cmp_by_key() or eq_by_key().

let lhs = [
    (1.0, "Lorem"),
    (2.0, "ipsum"),
    (f64::NAN, "dolor"),
    (4.0, "sit"),
    (5.0, "amet"),
];
let rhs = [
    (5.0, "Lorem"),
    (1.0, "ipsum"),
    (2.0, "dolor"),
    (3.0, "sit"),
    (f64::NAN, "amet"),
];
let ordering = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .partial_cmp_by_key(|x| x.0);
assert_eq!(ordering, Some(Ordering::Less));
Source

fn partial_cmp_by_keys<T, U, A, B, F, G>(self, f: F, g: G) -> Option<Ordering>
where Self: ParallelIterator<Item = (T, U)>, F: Fn(T) -> A + Sync, G: Fn(U) -> B + Sync, A: PartialOrd<B>,

Compare the pairs of items produced by this iterator using lexicographic order, after mapping them with f and g.

See also the other comparison adaptors such as partial_cmp_by_key(), cmp_by_keys() or eq_by_keys().

let lhs = [(1, 1.0), (2, 2.0), (3, 3.0), (4, f64::NAN), (5, 5.0)];
let rhs = [
    (5.0, "Lorem"),
    (1.0, "ipsum"),
    (f64::NAN, "dolor"),
    (3.0, "sit"),
    (4.0, "amet"),
];
let ordering = (lhs.par_iter(), rhs.par_iter())
    .zip_eq()
    .with_thread_pool(&mut thread_pool)
    .partial_cmp_by_keys(|x| x.1, |y| y.0);
assert_eq!(ordering, Some(Ordering::Less));
Source

fn product<T>(self) -> T
where T: Product<Self::Item> + Product<T> + Send,

Returns the product of the items produced by this iterator.

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let product = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .product::<i32>();
assert_eq!(product, 3628800);
Source

fn reduce<Init, F>(self, init: Init, f: F) -> Self::Item
where Init: Fn() -> Self::Item + Sync, F: Fn(Self::Item, Self::Item) -> Self::Item + Sync, Self::Item: Send,

Reduces the items produced by this iterator into a single item, using f to collapse pairs of items.

See also try_reduce().

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let sum = input
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .reduce(|| 0, |x, y| x + y);
assert_eq!(sum, 5 * 11);

Under the hood, each worker thread may call init and f in arbitrary order, therefore this method is mainly useful under the following conditions.

  • The reduction function f should be both commutative and associative, otherwise the result isn’t deterministic. For example, addition on floating-point numbers (e.g. f32, f64) is commutative but not associative.
  • The init function should return a neutral (a.k.a. identity) element with respect to f, that may be inserted anywhere in the computation. In particular, reduce() returns init() if the iterator is empty.
let sum = []
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .reduce(|| 0, |x, y| x + y);
assert_eq!(sum, 0);
Source

fn sum<T>(self) -> T
where T: Sum<Self::Item> + Sum<T> + Send,

Returns the sum of the items produced by this iterator.

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let sum = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .sum::<i32>();
assert_eq!(sum, 5 * 11);
Source

fn try_collect_per_thread<C>( self, ) -> <<Self::Item as Try>::Residual as Residual<Vec<C>>>::TryType
where Self::Item: Try, <Self::Item as Try>::Residual: Residual<C> + Residual<Vec<C>>, C: FromIterator<<Self::Item as Try>::Output> + Send, <<Self::Item as Try>::Residual as Residual<C>>::TryType: Send,

Available on crate feature nightly only.

Try collecting items from this iterator into a per-thread collection of type C, then aggregating these into a Vec<C> without further flattening, breaking early and returning the failure if any item contains a failure.

See also collect_per_thread() and fold_per_thread().

§Stability blockers

On stable Rust, this adaptor is currently only implemented for Result items. Items of arbitrary Try types are only available on Rust nightly with the nightly feature of Paralight enabled. This is because the implementation depends on the try_trait_v2 and try_trait_v2_residual nightly Rust features.

let input = [Ok(1), Ok(2), Ok(3), Ok(4), Ok(5), Ok(6), Ok(7), Ok(8)];
let collection: Result<Vec<Vec<i32>>, i32> = input
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .try_collect_per_thread();
assert!(collection.is_ok());

let mut values: Vec<i32> = collection.unwrap().into_iter().flatten().collect();
values.sort_unstable();
assert_eq!(values, &[1, 2, 3, 4, 5, 6, 7, 8]);
let input = [Ok(1), Err(2), Ok(3), Err(4), Ok(5), Err(6), Ok(7), Err(8)];
let collection: Result<Vec<Vec<i32>>, i32> = input
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .try_collect_per_thread();
assert!(collection.is_err());
assert!(collection.unwrap_err() % 2 == 0);

The outer type of the result is currently always Vec, but the inner type can be anything that implements FromIterator.

let input = [Ok(1), Ok(2), Ok(3), Ok(4), Ok(5), Ok(6), Ok(7), Ok(8)];
let collection: Result<Vec<HashSet<i32>>, i32> = input
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .try_collect_per_thread();
assert!(collection.is_ok());

let mut values: Vec<i32> = collection.unwrap().into_iter().flatten().collect();
values.sort_unstable();
assert_eq!(values, &[1, 2, 3, 4, 5, 6, 7, 8]);

With the nightly feature on a nightly compiler:

let input = [Some(1), Some(2), Some(3), Some(4), Some(5), Some(6)];
let collection: Option<Vec<Vec<i32>>> = input
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .try_collect_per_thread();
assert!(collection.is_some());

let mut values: Vec<i32> = collection.unwrap().into_iter().flatten().collect();
values.sort_unstable();
assert_eq!(values, &[1, 2, 3, 4, 5, 6]);
let input = [Some(1), None, Some(3), None, Some(5), None];
let collection: Option<Vec<Vec<i32>>> = input
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .try_collect_per_thread();
assert_eq!(collection, None);
let input = [Some(1), Some(2), Some(3), Some(4), Some(5), Some(6)];
let collection: Option<Vec<HashSet<i32>>> = input
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .try_collect_per_thread();
assert!(collection.is_some());

let mut values: Vec<i32> = collection.unwrap().into_iter().flatten().collect();
values.sort_unstable();
assert_eq!(values, &[1, 2, 3, 4, 5, 6]);
Source

fn try_fold_per_thread<T, U, R, S, InitPerThread, TryFoldPerThread, InitFinal, TryFoldFinal>( self, init_per_thread: InitPerThread, try_fold_per_thread: TryFoldPerThread, init_final: InitFinal, try_fold_final: TryFoldFinal, ) -> S
where InitPerThread: Fn() -> T + Sync, TryFoldPerThread: Fn(T, Self::Item) -> R + Sync, InitFinal: Fn(usize) -> U, TryFoldFinal: Fn(U, R) -> S, R: Try<Output = T> + Send, S: Try<Output = U>,

Available on crate feature nightly only.

Try folding items of this parallel iterator into a per-thread accumulator of type T, then folds again the per-thread results into an output of type U, breaking early and returning the failure if any operation returns a failure.

See also fold_per_thread().

§Stability blockers

On stable Rust, this adaptor is currently only implemented for Result outputs. Outputs of arbitrary Try types are only available on Rust nightly with the nightly feature of Paralight enabled. This is because the implementation depends on the try_trait_v2 nightly Rust feature.

let input: [Result<i32, i32>; 8] = [Ok(1), Ok(2), Ok(3), Ok(4), Ok(5), Ok(6), Ok(7), Ok(8)];
let collection: Result<Vec<Vec<i32>>, i32> = input
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .try_fold_per_thread(
        Vec::new,
        |mut vec, x| -> Result<Vec<i32>, i32> {
            vec.push(x?);
            Ok(vec)
        },
        Vec::with_capacity,
        |mut vecvec, vec| {
            vecvec.push(vec?);
            Ok(vecvec)
        },
    );
assert!(collection.is_ok());

let mut values: Vec<i32> = collection.unwrap().into_iter().flatten().collect();
values.sort_unstable();
assert_eq!(values, &[1, 2, 3, 4, 5, 6, 7, 8]);
let input = [Ok(1), Ok(2), Ok(3), Ok(4), Err(5), Ok(6), Ok(7), Ok(8)];
let collection: Result<Vec<Vec<i32>>, i32> = input
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .try_fold_per_thread(
        Vec::new,
        |mut vec, x| -> Result<Vec<i32>, i32> {
            vec.push(x?);
            Ok(vec)
        },
        Vec::with_capacity,
        |mut vecvec, vec| {
            vecvec.push(vec?);
            Ok(vecvec)
        },
    );
assert_eq!(collection, Err(5));

With the nightly feature on a nightly compiler:

let input = [Some(1), Some(2), Some(3), Some(4), Some(5), Some(6)];
let collection: Option<Vec<Vec<i32>>> = input
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .try_fold_per_thread(
        Vec::new,
        |mut vec, x| {
            vec.push(x?);
            Some(vec)
        },
        Vec::with_capacity,
        |mut vecvec, vec| {
            vecvec.push(vec?);
            Some(vecvec)
        },
    );
assert!(collection.is_some());

let mut values: Vec<i32> = collection.unwrap().into_iter().flatten().collect();
values.sort_unstable();
assert_eq!(values, &[1, 2, 3, 4, 5, 6]);
let input = [Some(1), Some(2), Some(3), Some(4), None, Some(6)];
let collection: Option<Vec<Vec<i32>>> = input
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .try_fold_per_thread(
        Vec::new,
        |mut vec, x| {
            vec.push(x?);
            Some(vec)
        },
        Vec::with_capacity,
        |mut vecvec, vec| {
            vecvec.push(vec?);
            Some(vecvec)
        },
    );
assert_eq!(collection, None);
Source

fn try_for_each<R, F>(self, f: F) -> R
where F: Fn(Self::Item) -> R + Sync, R: Try<Output = ()> + Send,

Available on crate feature nightly only.

Runs the fallible function f on each item of this parallel iterator, breaking early and returning the failure in case of failure.

If multiple items cause a failure, an arbitrary one is returned.

See also try_for_each_init() if you need to initialize a per-thread value and pass it together with each item.

§Stability blockers

On stable Rust, this adaptor is currently only implemented for Result outputs. Outputs of arbitrary Try types are only available on Rust nightly with the nightly feature of Paralight enabled. This is because the implementation depends on the try_trait_v2 nightly Rust feature.

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let set = Mutex::new(HashSet::new());
let result = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .try_for_each(|&x| {
        if set.lock().unwrap().insert(x) {
            Ok(())
        } else {
            Err(x)
        }
    });
assert_eq!(result, Ok(()));
assert_eq!(set.into_inner().unwrap(), (1..=10).collect());
let input = [1, 1, 1, 1, 1, 6, 7, 8, 9, 10];
let set = Mutex::new(HashSet::new());
let result = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .try_for_each(|&x| {
        if set.lock().unwrap().insert(x) {
            Ok(())
        } else {
            Err(x)
        }
    });
assert_eq!(result, Err(1));
let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let result = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .try_for_each(|&x| Err(x));
assert!(result.is_err());

With the nightly feature on a nightly compiler:

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let set = Mutex::new(HashSet::new());
let result = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .try_for_each(|&x| {
        if set.lock().unwrap().insert(x) {
            Some(())
        } else {
            None
        }
    });
assert_eq!(result, Some(()));
assert_eq!(set.into_inner().unwrap(), (1..=10).collect());
let input = [1, 1, 1, 1, 1, 6, 7, 8, 9, 10];
let set = Mutex::new(HashSet::new());
let result = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .try_for_each(|&x| {
        if set.lock().unwrap().insert(x) {
            Some(())
        } else {
            None
        }
    });
assert_eq!(result, None);
let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let result = input
    .par_iter()
    .with_thread_pool(&mut thread_pool)
    .try_for_each(|_| None);
assert!(result.is_none());
Source

fn try_for_each_init<T, Init, R, F>(self, init: Init, f: F) -> R
where Init: Fn() -> T + Sync, F: Fn(&mut T, Self::Item) -> R + Sync, R: Try<Output = ()> + Send,

Available on crate feature nightly only.

Runs the fallible function f on each item of this parallel iterator, together with a per-thread mutable value returned by init, breaking early and returning the failure in case of failure.

If multiple items cause a failure, an arbitrary one is returned.

The init function will be called only once per worker thread. The companion value returned by init doesn’t need to be Send nor Sync.

§Stability blockers

On stable Rust, this adaptor is currently only implemented for Result outputs. Outputs of arbitrary Try types are only available on Rust nightly with the nightly feature of Paralight enabled. This is because the implementation depends on the try_trait_v2 nightly Rust feature.

use rand::RngExt;

let set = Mutex::new(HashSet::new());
let result = (0..257)
    .into_par_iter()
    .with_thread_pool(&mut thread_pool)
    .try_for_each_init(
        rand::rng, // A thread-local RNG that is neither Send nor Sync.
        |rng, _| {
            let byte: u8 = rng.random();
            if set.lock().unwrap().insert(byte) {
                Ok(())
            } else {
                Err(byte)
            }
        },
    );
// Even a biased random number generator cannot yield more than 256 distinct bytes.
assert!(result.is_err());

With the nightly feature on a nightly compiler:

use rand::RngExt;

let set = Mutex::new(HashSet::new());
let result = (0..257)
    .into_par_iter()
    .with_thread_pool(&mut thread_pool)
    .try_for_each_init(
        rand::rng, // A thread-local RNG that is neither Send nor Sync.
        |rng, _| {
            let byte: u8 = rng.random();
            if set.lock().unwrap().insert(byte) {
                Some(())
            } else {
                None
            }
        },
    );
// Even a biased random number generator cannot yield more than 256 distinct bytes.
assert!(result.is_none());
Source

fn try_reduce<R, Init, F>(self, init: Init, f: F) -> R
where Init: Fn() -> Self::Item + Sync, F: Fn(Self::Item, Self::Item) -> R + Sync, R: Try<Output = Self::Item> + Send,

Available on crate feature nightly only.

Try reducing the items produced by this iterator into a single item, using f to collapse pairs of items, breaking early and returning the failure if f returns a failure.

If multiple failures happen, an arbitrary one is returned.

See also reduce().

§Stability blockers

On stable Rust, this adaptor is currently only implemented for Result outputs. Outputs of arbitrary Try types are only available on Rust nightly with the nightly feature of Paralight enabled. This is because the implementation depends on the try_trait_v2 nightly Rust feature.

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let sum = input
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .try_reduce(|| 0i32, |x, y| x.checked_add(y).ok_or("error"));
assert_eq!(sum, Ok(5 * 11));
let input = [1, 2, 3, 4, i32::MAX, 6, 7, 8, 9, 10];
let sum = input
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .try_reduce(|| 0i32, |x, y| x.checked_add(y).ok_or("error"));
assert_eq!(sum, Err("error"));
let sum = []
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .try_reduce(|| 0i32, |x, y| x.checked_add(y).ok_or("error"));
assert_eq!(sum, Ok(0));

With the nightly feature on a nightly compiler:

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let sum = input
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .try_reduce(|| 0i32, |x, y| x.checked_add(y));
assert_eq!(sum, Some(5 * 11));
let input = [1, 2, 3, 4, i32::MAX, 6, 7, 8, 9, 10];
let sum = input
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .try_reduce(|| 0i32, |x, y| x.checked_add(y));
assert_eq!(sum, None);
let sum = []
    .par_iter()
    .copied()
    .with_thread_pool(&mut thread_pool)
    .try_reduce(|| 0i32, |x, y| x.checked_add(y));
assert_eq!(sum, Some(0));

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§