Skip to main content

ExactParallelSourceExt

Trait ExactParallelSourceExt 

Source
pub trait ExactParallelSourceExt: ExactParallelSource {
Show 20 methods // Provided methods fn array_windows<const N: usize>(self) -> ArrayWindows<Self, N> where Self: RewindableSource { ... } fn chain<T: ExactParallelSource<Item = Self::Item>>( self, next: T, ) -> Chain<Self, T> { ... } fn cloned<'a, T>(self) -> Cloned<Self> where Self: ExactParallelSource<Item = &'a T>, T: Clone + 'a { ... } fn copied<'a, T>(self) -> Copied<Self> where Self: ExactParallelSource<Item = &'a T>, T: Copy + 'a { ... } fn cycle(self, n: usize) -> Cycle<Self> where Self: RewindableSource { ... } fn downgrade(self) -> Downgrade<Self> { ... } fn enumerate(self) -> Enumerate<Self> { ... } fn filter<F>(self, f: F) -> FilterExact<Self, F> where F: Fn(&Self::Item) -> bool + Sync { ... } fn filter_map<T, F>(self, f: F) -> FilterMapExact<Self, F> where F: Fn(Self::Item) -> Option<T> + Sync { ... } fn inspect<F>(self, f: F) -> Inspect<Self, F> where F: Fn(&Self::Item) + Sync { ... } fn map<T, F>(self, f: F) -> MapSource<Self, F> where F: Fn(Self::Item) -> T + Sync { ... } fn map_init<I, Init, T, F>(self, init: Init, f: F) -> MapInit<Self, Init, F> where Init: Fn() -> I + Sync, F: Fn(&mut I, Self::Item) -> T + Sync { ... } fn rev(self) -> Rev<Self> { ... } fn skip(self, n: usize) -> Skip<Self> { ... } fn skip_exact(self, n: usize) -> SkipExact<Self> { ... } fn step_by(self, n: usize) -> StepBy<Self> { ... } fn take(self, n: usize) -> Take<Self> { ... } fn take_exact(self, n: usize) -> TakeExact<Self> { ... } fn update<F>(self, f: F) -> Update<Self, F> where F: Fn(&mut Self::Item) + Sync { ... } fn with_thread_pool<T: GenericThreadPool>( self, thread_pool: T, ) -> BaseExactParallelIterator<T, Self> { ... }
}
Expand description

Additional methods provided for types that implement ExactParallelSource.

Provided Methods§

Source

fn array_windows<const N: usize>(self) -> ArrayWindows<Self, N>
where Self: RewindableSource,

Returns a parallel source that produces overlapping arrays of N contiguous items from this source.

let input = [1, 2, 3, 4, 5];
let collection: Vec<_> = input
    .par_iter()
    .copied()
    .array_windows()
    .with_thread_pool(&mut thread_pool)
    .collect();
assert_eq!(collection, [[1, 2], [2, 3], [3, 4], [4, 5]]);

You can leverage this adaptor to build more complex pipelines, such as checking if a slice is sorted.

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let is_sorted = input
    .par_iter()
    .array_windows()
    .with_thread_pool(&mut thread_pool)
    .all(|[x, y]| x < y);
assert!(is_sorted);

If the window size exceeds the input length, the resulting parallel source is empty. However, a window size that matches the input length produces exactly one item.

let input = [1, 2, 3, 4, 5];

let collection: Vec<_> = input
    .par_iter()
    .copied()
    .array_windows::<5>()
    .with_thread_pool(&mut thread_pool)
    .collect();
assert_eq!(collection, [[1, 2, 3, 4, 5]]);
let input = [1, 2, 3, 4, 5];

let collection: Vec<_> = input
    .par_iter()
    .copied()
    .array_windows::<6>()
    .with_thread_pool(&mut thread_pool)
    .collect();
assert!(collection.is_empty());

This doesn’t compile if the window length N is zero, even if the underlying source is empty.

ⓘ
let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
input
    .par_iter()
    .array_windows::<0>()
    .with_thread_pool(&mut thread_pool)
    .for_each(|[]| ());
ⓘ
let input: [i32; 0] = [];
input
    .par_iter()
    .array_windows::<0>()
    .with_thread_pool(&mut thread_pool)
    .for_each(|[]| ());
Source

fn chain<T: ExactParallelSource<Item = Self::Item>>( self, next: T, ) -> Chain<Self, T>

Returns a parallel source that produces items from this source followed by items from the next source.

Note: Given that items are processed in arbitrary order (in WorkStealing mode), the order in which sources are chained doesn’t necessarily matter, but can be relevant when combined with order-sensitive adaptors (e.g. enumerate(), take(), etc.).

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

fn cloned<'a, T>(self) -> Cloned<Self>
where Self: ExactParallelSource<Item = &'a T>, T: Clone + 'a,

Returns a parallel source that produces items that are cloned from the items of this source. This is useful if you have a source over &T and want a source over T, when T is Clone.

This is equivalent to calling .map(|x| x.clone()).

See also copied().

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

fn copied<'a, T>(self) -> Copied<Self>
where Self: ExactParallelSource<Item = &'a T>, T: Copy + 'a,

Returns a parallel source that produces items that are copied from the items of this source. This is useful if you have a source over &T and want a source over T, when T is Copy.

This is equivalent to calling .map(|x| *x).

See also cloned().

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);
Source

fn cycle(self, n: usize) -> Cycle<Self>
where Self: RewindableSource,

Returns a parallel source that produces items from this source the given number of times.

In terms of logical order, it produces all the items once, then produces them all again from the beginning, and so on the requested number of times.

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

fn downgrade(self) -> Downgrade<Self>

Transforms this ExactParallelSource into an equivalent ParallelSource.

This is useful to combine multiple ExactParallelSources and ParallelSources together, for example with the chain() adaptor.

let first = [1, 2, 3];
let second = [4, 5, 6, 7, 8, 9, 10];
let sum = first
    .par_iter()
    .downgrade() // Needed to chain with the filtered source below.
    .chain(second.par_iter().filter(|&x| x % 2 == 0))
    .with_thread_pool(&mut thread_pool)
    .sum::<i32>();
assert_eq!(sum, 1 + 2 + 3 + 4 + 6 + 8 + 10);

Without downgrading, an ExactParallelSource cannot be chained with a ParallelSource.

ⓘ
let first = [1, 2, 3];
let second = [4, 5, 6, 7, 8, 9, 10];
let sum = first
    .par_iter()
    .chain(second.par_iter().filter(|&x| x % 2 == 0))
    .with_thread_pool(&mut thread_pool)
    .sum::<i32>();
assert_eq!(sum, 1 + 2 + 3 + 4 + 6 + 8 + 10);
Source

fn enumerate(self) -> Enumerate<Self>

Returns a parallel source that produces pairs of (index, item) for the items of this source.

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

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

Returns a parallel source that produces only the items for which the predicate f returns true.

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

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

Applies the function f to each item of this source, returning a parallel source that produces the mapped items x for which f returns Some(x) and skips the items for which f returns None.

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let sum = input
    .par_iter()
    .filter_map(|&x| if x != 2 { Some(x * 3) } else { None })
    .with_thread_pool(&mut thread_pool)
    .sum::<i32>();
assert_eq!(sum, 3 * (5 * 11 - 2));

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_even = input
    .par_iter()
    .filter_map(|&x| if x % 2 == 0 { Some(Rc::new(x)) } else { None })
    .with_thread_pool(&mut thread_pool)
    .pipeline(|| 0, |acc, x| acc + *x, |acc| acc, |a, b| a + b);
assert_eq!(sum_even, 5 * 6);
Source

fn inspect<F>(self, f: F) -> Inspect<Self, F>
where F: Fn(&Self::Item) + Sync,

Runs the function f on each item of this source in a pass-through manner, returning a parallel source producing the original items.

This is useful to help debug intermediate stages of an iterator adaptor pipeline.

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let inspections = AtomicUsize::new(0);

let min = input
    .par_iter()
    .inspect(|x| {
        println!("[{:?}] x = {x}", std::thread::current().id());
        inspections.fetch_add(1, Ordering::Relaxed);
    })
    .with_thread_pool(&mut thread_pool)
    .min();

assert_eq!(min, Some(&1));
assert_eq!(inspections.load(Ordering::Relaxed), 10);
Source

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

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

See also map_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 double_sum = input
    .par_iter()
    .map(|&x| x * 2)
    .with_thread_pool(&mut thread_pool)
    .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()
    .map(|&x| Rc::new(x))
    .with_thread_pool(&mut thread_pool)
    .pipeline(|| 0, |acc, x| acc + *x, |acc| acc, |a, b| a + b);
assert_eq!(sum, 5 * 11);
Source

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

Applies the function f to each item of this source, together with a per-thread mutable value returned by init, and returns a parallel source producing the mapped items.

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 input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let randomized_sum = input
    .par_iter()
    .map_init(
        rand::rng, // A thread-local RNG that is neither Send nor Sync.
        |rng, &x| if rng.random() { x * 2 } else { x * 3 },
    )
    .with_thread_pool(&mut thread_pool)
    .sum::<i32>();

assert!(randomized_sum >= 10 * 11);
assert!(randomized_sum <= 15 * 11);
Source

fn rev(self) -> Rev<Self>

Returns a parallel source that produces items from this source in reverse order.

Note: Given that items are processed in arbitrary order (in WorkStealing mode), this isn’t very useful on its own, but can be relevant when combined with order-sensitive adaptors (e.g. enumerate(), take(), etc.).

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

fn skip(self, n: usize) -> Skip<Self>

Returns a parallel source that skips the first n items from this source, or all the items if this source has fewer than n items, and produces the remaining items.

See also skip_exact() for a variant that panics if this source has fewer than n items.

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

fn skip_exact(self, n: usize) -> SkipExact<Self>

Returns a parallel source that skips the first n items from this source, panicking if this source has fewer than n items, and produces the remaining items.

See also skip() for a variant that doesn’t panic but produces no item if this source has fewer than n items.

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

fn step_by(self, n: usize) -> StepBy<Self>

Returns a parallel source that produces every n-th item from this source, starting with the first one.

In other words, the returned source produces the items at indices 0, n, 2*n, etc.

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

let sum = input
    .par_iter()
    .step_by(2)
    .with_thread_pool(&mut thread_pool)
    .sum::<i32>();
assert_eq!(sum, 1 + 3 + 5 + 7 + 9);

let sum = input
    .par_iter()
    .step_by(3)
    .with_thread_pool(&mut thread_pool)
    .sum::<i32>();
assert_eq!(sum, 1 + 4 + 7 + 10);

This panics if the step is zero, even if the underlying source is empty.

ⓘ
let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let _ = input
    .par_iter()
    .step_by(0)
    .with_thread_pool(&mut thread_pool)
    .sum::<i32>();
ⓘ
let _ = []
    .par_iter()
    .step_by(0)
    .with_thread_pool(&mut thread_pool)
    .sum::<i32>();
Source

fn take(self, n: usize) -> Take<Self>

Returns a parallel source that produces the first n items from this source, or all the items if this source has fewer than n items.

See also take_exact() for a variant that panics if this source has fewer than n items.

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

fn take_exact(self, n: usize) -> TakeExact<Self>

Returns a parallel source that produces the first n items from this source, panicking if this source has fewer than n items.

See also take() for a variant that doesn’t panic but produces all the items if this source has fewer than n items.

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

fn update<F>(self, f: F) -> Update<Self, F>
where F: Fn(&mut Self::Item) + Sync,

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

let mut values = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let double_sum = values
    .par_iter_mut()
    .update(|x| **x *= 2)
    .map(|x| *x)
    .with_thread_pool(&mut thread_pool)
    .sum::<i32>();
assert_eq!(double_sum, 10 * 11);
assert_eq!(values, [2, 4, 6, 8, 10, 12, 14, 16, 18, 20]);
Source

fn with_thread_pool<T: GenericThreadPool>( self, thread_pool: T, ) -> BaseExactParallelIterator<T, Self>

Attaches the given GenericThreadPool to this ExactParallelSource and obtain a ParallelIterator.

let mut thread_pool = ThreadPoolBuilder {
    num_threads: ThreadCount::AvailableParallelism,
    range_strategy: RangeStrategy::WorkStealing,
    cpu_pinning: CpuPinningPolicy::No,
}
.build();

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);

Dyn Compatibility§

This trait is not dyn compatible.

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

Implementors§