Skip to main content

ParallelSourceExt

Trait ParallelSourceExt 

Source
pub trait ParallelSourceExt: ParallelSource {
    // Provided methods
    fn chain<T: ParallelSource<Item = Self::Item>>(
        self,
        next: T,
    ) -> Chain<Self, T> { ... }
    fn cloned<'a, T>(self) -> Cloned<Self>
       where Self: ParallelSource<Item = &'a T>,
             T: Clone + 'a { ... }
    fn copied<'a, T>(self) -> Copied<Self>
       where Self: ParallelSource<Item = &'a T>,
             T: Copy + 'a { ... }
    fn cycle(self, n: usize) -> Cycle<Self>
       where Self: RewindableSource { ... }
    fn filter<F>(self, f: F) -> Filter<Self, F>
       where F: Fn(&Self::Item) -> bool + Sync { ... }
    fn filter_map<T, F>(self, f: F) -> FilterMap<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 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,
    ) -> BaseParallelIterator<T, Self> { ... }
}
Expand description

Additional methods provided for types that implement ParallelSource.

Provided Methods§

Source

fn chain<T: ParallelSource<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];
let sum = first
    .par_iter()
    .downgrade() // ExactParallelSource -> ParallelSource
    .chain(second.par_iter().downgrade())
    .with_thread_pool(&mut thread_pool)
    .sum::<i32>();
assert_eq!(sum, 5 * 11);
Source

fn cloned<'a, T>(self) -> Cloned<Self>
where Self: ParallelSource<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()
    .downgrade() // ExactParallelSource -> ParallelSource
    .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: ParallelSource<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()
    .downgrade() // ExactParallelSource -> ParallelSource
    .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()
    .downgrade() // ExactParallelSource -> ParallelSource
    .cycle(7)
    .with_thread_pool(&mut thread_pool)
    .sum::<i32>();
assert_eq!(repeated_sum, 7 * 5 * 11);
Source

fn filter<F>(self, f: F) -> Filter<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()
    .downgrade() // ExactParallelSource -> ParallelSource
    .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) -> FilterMap<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()
    .downgrade() // ExactParallelSource -> ParallelSource
    .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()
    .downgrade() // ExactParallelSource -> ParallelSource
    .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()
    .downgrade() // ExactParallelSource -> ParallelSource
    .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()
    .downgrade() // ExactParallelSource -> ParallelSource
    .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()
    .downgrade() // ExactParallelSource -> ParallelSource
    .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()
    .downgrade() // ExactParallelSource -> ParallelSource
    .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. find_first()).

let input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
let first_odd = input
    .par_iter()
    .downgrade() // ExactParallelSource -> ParallelSource
    .rev()
    .with_thread_pool(&mut thread_pool)
    .find_first(|&&x| x % 2 != 0);
assert_eq!(first_odd, Some(&9));
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()
    .downgrade() // ExactParallelSource -> ParallelSource
    .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, ) -> BaseParallelIterator<T, Self>

Attaches the given GenericThreadPool to this ParallelSource 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()
    .downgrade() // ExactParallelSource -> ParallelSource
    .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§