Rayon

https://docs.rs/rayon/latest/rayon/
Admin
Rayon is a data-parallelism library for Rust that makes it easy to convert sequential computations...
Tokens:1,050,200
Snippets:6,448
Trust Score:9.1
Update:1 week ago
Show doc for...
Tokens:
Raw
### Using install() to run a closure in the pool

Source: https://docs.rs/rayon/latest/rayon/struct.ThreadPool.html

Shows how to use install() to execute a closure that uses rayon::join inside the pool, with a fib function example.

```rust
   fn main() {
        let pool = rayon::ThreadPoolBuilder::new().num_threads(8).build().unwrap();
        let n = pool.install(|| fib(20));
        println!("{}", n);
   }

   fn fib(n: usize) -> usize {
        if n == 0 || n == 1 {
            return n;
        }
        let (a, b) = rayon::join(|| fib(n - 1), || fib(n - 2)); // runs inside of `pool`
        return a + b;
    }
```

--------------------------------

### partial_cmp: Example (incomplete)

Source: https://docs.rs/rayon/latest/rayon/iter/trait.IndexedParallelIterator.html

This example is incomplete in the source; it only shows the imports and starts the partial_cmp example.

```rust
use rayon::prelude::*;
use std::cmp::Ordering::*;


```

--------------------------------

### Example of install() with execution order warning

Source: https://docs.rs/rayon/latest/rayon/struct.ThreadPool.html

Demonstrates the execution order warning for install(): when the current thread is part of a different pool, install() yields implicitly, allowing other tasks to run concurrently.

```rust
fn main() {
    rayon::ThreadPoolBuilder::new().num_threads(1).build_global().unwrap();
    let pool = rayon_core::ThreadPoolBuilder::default().build().unwrap();
    let do_it = || {
        print!("one ");
        pool.install(||{});
        print!("two ");
    };
    rayon::join(|| do_it(), || do_it());
}
```

```text
one two one two
```

```text
one one two two
```

--------------------------------

### Example of install() yielding execution order

Source: https://docs.rs/rayon/latest/rayon/struct.ThreadPool.html?search=

Shows that install() yields implicitly, allowing multiple instances of do_it() to run concurrently on a single global thread, producing output like 'one two one two' or 'one one two two'.

```rust
fn main() {
    rayon::ThreadPoolBuilder::new().num_threads(1).build_global().unwrap();
    let pool = rayon_core::ThreadPoolBuilder::default().build().unwrap();
    let do_it = || {
        print!("one ");
        pool.install(||{});
        print!("two ");
    };
    rayon::join(|| do_it(), || do_it());
}
```

--------------------------------

### Quick-sort example using rayon::join

Source: https://docs.rs/rayon/latest/rayon/fn.join.html

Example usage of `rayon::join` to perform a quick-sort on a vector. The example includes the `quick_sort` and `partition` functions. Note that this is not an optimized implementation; prefer `par_sort` for real sorting.

```rust
let mut v = vec![5, 1, 8, 22, 0, 44];
quick_sort(&mut v);
assert_eq!(v, vec![0, 1, 5, 8, 22, 44]);

fn quick_sort<T:PartialOrd+Send>(v: &mut [T]) {
   if v.len() > 1 {
       let mid = partition(v);
       let (lo, hi) = v.split_at_mut(mid);
       rayon::join(|| quick_sort(lo),
                   || quick_sort(hi));
   }
}

// Partition rearranges all items `<=` to the pivot
// item (arbitrary selected to be the last item in the slice)
// to the first half of the slice. It then returns the
// "dividing point" where the pivot is placed.
fn partition<T:PartialOrd+Send>(v: &mut [T]) -> usize {
    let pivot = v.len() - 1;
    let mut i = 0;
    for j in 0..pivot {
        if v[j] <= v[pivot] {
            v.swap(i, j);
            i += 1;
        }
    }
    v.swap(i, pivot);
    i
}

```

--------------------------------

### take example

Source: https://docs.rs/rayon/latest/rayon/iter/trait.IndexedParallelIterator.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates an iterator that yields the first n elements. The example takes the first 5 elements of a range.

```rust
use rayon::prelude::*;

let result: Vec<_> = (0..100)
    .into_par_iter()
    .take(5)
    .collect();

assert_eq!(result, [0, 1, 2, 3, 4]);
```

--------------------------------

### step_by example

Source: https://docs.rs/rayon/latest/rayon/iter/trait.IndexedParallelIterator.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Creates an iterator that steps by the given amount. The example collects every third element from a range.

```rust
use rayon::prelude::*;

let range = (3..10);
let result: Vec<i32> = range
   .into_par_iter()
   .step_by(3)
   .collect();

assert_eq!(result, [3, 6, 9])
```

--------------------------------

### Example of spawning tasks with scope_fifo

Source: https://docs.rs/rayon/latest/rayon/fn.scope_fifo.html?search=u32+-%3E+bool

An example showing how to use scope_fifo to spawn tasks with FIFO order. Tasks are spawned with spawn_fifo, and nested scopes are used. The example is used to illustrate the execution order of tasks.

```rust
// point start
rayon::scope_fifo(|s| {
    s.spawn_fifo(|s| { // task s.1
        s.spawn_fifo(|s| { // task s.1.1
            rayon::scope_fifo(|t| {
                t.spawn_fifo(|_| ()); // task t.1
                t.spawn_fifo(|_| ()); // task t.2
            });
        });
    });
    s.spawn_fifo(|s| { // task s.2
    });
    // point mid
});
// point end
```

--------------------------------

### enumerate example

Source: https://docs.rs/rayon/latest/rayon/iter/trait.IndexedParallelIterator.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Yields an index along with each item. The example collects into a vector of tuples.

```rust
use rayon::prelude::*;

let chars = vec!['a', 'b', 'c'];
let result: Vec<_> = chars
    .into_par_iter()
    .enumerate()
    .collect();

assert_eq!(result, [(0, 'a'), (1, 'b'), (2, 'c')]);
```

--------------------------------

### zip_eq example (panics on length mismatch)

Source: https://docs.rs/rayon/latest/rayon/iter/trait.IndexedParallelIterator.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to use zip_eq, which panics if the two iterators are not the same length. The example is marked as panicking.

```rust
use rayon::prelude::*;

let one = [1u8];
let two = [2u8, 2];
let one_iter = one.par_iter();
let two_iter = two.par_iter();

// this will panic
let zipped: Vec<(&u8, &u8)> = one_iter.zip_eq(two_iter).collect();
```

--------------------------------

### position_any example

Source: https://docs.rs/rayon/latest/rayon/iter/trait.IndexedParallelIterator.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Searches for some item matching the predicate and returns its index. The example shows that the index may be 2 or 3 for the value 3.

```rust
use rayon::prelude::*;

let a = [1, 2, 3, 3];

let i = a.par_iter().position_any(|&x| x == 3).expect("found");
assert!(i == 2 || i == 3);

assert_eq!(a.par_iter().position_any(|&x| x == 100), None);
```

--------------------------------

### positions example

Source: https://docs.rs/rayon/latest/rayon/iter/trait.IndexedParallelIterator.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Collects indices of all elements matching a predicate. The example finds primes congruent to 1 and 5 modulo 6.

```rust
use rayon::prelude::*;

let primes = vec![2, 3, 5, 7, 11, 13, 17, 19, 23, 29];

// Find the positions of primes congruent to 1 modulo 6
let p1mod6: Vec<_> = primes.par_iter().positions(|&p| p % 6 == 1).collect();
assert_eq!(p1mod6, [3, 5, 7]); // primes 7, 13, and 19

// Find the positions of primes congruent to 5 modulo 6
let p5mod6: Vec<_> = primes.par_iter().positions(|&p| p % 6 == 5).collect();
assert_eq!(p5mod6, [2, 4, 6, 8, 9]); // primes 5, 11, 17, 23, and 29
```

--------------------------------

### position_first example

Source: https://docs.rs/rayon/latest/rayon/iter/trait.IndexedParallelIterator.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Searches for the sequentially first item matching the predicate and returns its index. The example shows that the first occurrence of 3 is at index 2.

```rust
use rayon::prelude::*;

let a = [1, 2, 3, 3];

assert_eq!(a.par_iter().position_first(|&x| x == 3), Some(2));
```

--------------------------------

### Example: Using len() on an IndexedParallelIterator

Source: https://docs.rs/rayon/latest/rayon/iter/trait.IndexedParallelIterator.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows how to use the len() method to get an exact count of items in a parallel iterator. The example creates a parallel iterator over a range zipped with a vector and asserts the length is 10.

```rust
use rayon::prelude::*;

let par_iter = (0..100).into_par_iter().zip(vec![0; 10]);
assert_eq!(par_iter.len(), 10);

let vec: Vec<_> = par_iter.collect();
assert_eq!(vec.len(), 10);
```

--------------------------------

### par_rchunks_mut example

Source: https://docs.rs/rayon/latest/rayon/slice/trait.ParallelSliceMut.html

Reverses each mutable chunk of at most 2 elements, starting from the end. The last chunk may be shorter if the length is not divisible by the chunk size.

```rust
use rayon::prelude::*;
let mut array = [1, 2, 3, 4, 5];
array.par_rchunks_mut(2)
     .for_each(|slice| slice.reverse());
assert_eq!(array, [1, 3, 2, 5, 4]);
```

--------------------------------

### Example: using Scope::spawn to spawn tasks

Source: https://docs.rs/rayon/latest/rayon/struct.Scope.html?search=std%3A%3Avec

Example from the documentation for Scope::spawn. It shows how to spawn tasks that write to local variables, and demonstrates that the scope waits for all spawned tasks to complete before the scope ends.

```rust
let mut value_a = None;
let mut value_b = None;
let mut value_c = None;
rayon::scope(|s| {
    s.spawn(|s1| {
          // ^ this is the same scope as `s`; this handle `s1`
          //   is intended for use by the spawned task,
          //   since scope handles cannot cross thread boundaries.

        value_a = Some(22);

        // the scope `s` will not end until all these tasks are done
        s1.spawn(|_| {
            value_b = Some(44);
        });
    });

    s.spawn(|_| {
        value_c = Some(66);
    });
});
assert_eq!(value_a, Some(22));
assert_eq!(value_b, Some(44));
assert_eq!(value_c, Some(66));
```

--------------------------------

### par_rchunks_exact_mut example

Source: https://docs.rs/rayon/latest/rayon/slice/trait.ParallelSliceMut.html

Reverses each mutable chunk of exactly 3 elements, starting from the end. If the chunk size does not divide the length, the last up to chunk_size-1 elements are omitted and can be retrieved from the remainder function.

```rust
use rayon::prelude::*;
let mut array = [1, 2, 3, 4, 5];
array.par_rchunks_exact_mut(3)
     .for_each(|slice| slice.reverse());
assert_eq!(array, [1, 2, 5, 4, 3]);
```

--------------------------------

### par_rchunks: parallel iterator over chunks from the end

Source: https://docs.rs/rayon/latest/rayon/slice/trait.ParallelSlice.html

Like par_chunks but processes chunks starting from the end of the slice; the first chunk (from the end) may be shorter. The example collects chunks of size 2 from five elements in reverse order.

```rust
use rayon::prelude::*;
let chunks: Vec<_> = [1, 2, 3, 4, 5].par_rchunks(2).collect();
assert_eq!(chunks, vec![&[4, 5][..], &[2, 3], &[1]]);
```

--------------------------------

### par_rchunks_exact: parallel iterator over exact chunks from the end

Source: https://docs.rs/rayon/latest/rayon/slice/trait.ParallelSlice.html

Like par_chunks_exact but processes chunks starting from the end; any remainder is omitted and can be retrieved from the iterator's remainder function. The example collects exact chunks of size 2 from five elements, dropping the first element.

```rust
use rayon::prelude::*;
let chunks: Vec<_> = [1, 2, 3, 4, 5].par_rchunks_exact(2).collect();
assert_eq!(chunks, vec![&[4, 5][..], &[2, 3]]);
```

--------------------------------

### Example tree diagram for walk_tree_postfix

Source: https://docs.rs/rayon/latest/rayon/iter/fn.walk_tree_postfix.html

A simple tree diagram used in the first example: root 4 with children 2 and 3, and 3 has children 1 and 2.

```text
     4
    / \
   /   \
  2     3
       / \
      1   2

```

--------------------------------

### Method: for_each_init

Source: https://docs.rs/rayon/latest/rayon/iter/struct.WalkTreePostfix.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Documentation for the `for_each_init` method on `WalkTreePostfix`, which executes an operation with a newly initialized state on each item.

```APIDOC
## [method] for_each_init<OP, INIT, T>(self, init: INIT, op: OP)

### Description
Executes `OP` on a value returned by `init` with each item produced by the iterator, in parallel.

### Signature
`fn for_each_init<OP, INIT, T>(self, init: INIT, op: OP) where OP: Fn(&mut T, Self::Item) + Sync + Send, INIT: Fn() -> T + Sync + Send`

### Parameters
- `init` (closure) - Required - A closure that returns a new `T` value for each parallel invocation.
- `op` (closure) - Required - The operation to execute with the mutable reference to the value and each item.

### Note
This is a method of the `ParallelIterator` trait, available on `WalkTreePostfix`.
```

--------------------------------

### Postfix ordering example with a perfect binary tree

Source: https://docs.rs/rayon/latest/rayon/iter/fn.walk_tree_postfix.html

Shows the reduction order for a perfect binary tree of 7 nodes: d,e,b,f,g,c,a. This illustrates the postfix ordering guarantee.

```text
     a
    / \
   /   \
  b     c
 / \   / \
d   e f   g

reduced as d,e,b,f,g,c,a

```

--------------------------------

### Method: try_for_each_init

Source: https://docs.rs/rayon/latest/rayon/iter/struct.WalkTreePostfix.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Documentation for the `try_for_each_init` method on `WalkTreePostfix`, which executes a fallible operation with a newly initialized state on each item.

```APIDOC
## [method] try_for_each_init<OP, INIT, T, R>(self, init: INIT, op: OP) -> R

### Description
Executes a fallible `OP` on a value returned by `init` with each item produced by the iterator, in parallel.

### Signature
`fn try_for_each_init<OP, INIT, T, R>(self, init: INIT, op: OP) -> R where OP: Fn(&mut T, Self::Item) -> R + Sync + Send, INIT: Fn() -> T + Sync + Send, R: Try<Output = ()> + Send`

### Parameters
- `init` (closure) - Required - A closure that returns a new `T` value for each parallel invocation.
- `op` (closure) - Required - The fallible operation to execute with the mutable reference to the value and each item.

### Returns
- `R` - The result of the operation, which implements `Try` with `Output = ()`.

### Note
This is a method of the `ParallelIterator` trait, available on `WalkTreePostfix`.
```

--------------------------------

### for_each example

Source: https://docs.rs/rayon/latest/rayon/iter/trait.ParallelIterator.html

Executes a closure on each item in parallel. The example prints numbers 0 to 99.

```rust
use rayon::prelude::*;

(0..100).into_par_iter().for_each(|x| println!("{:?}", x));
```

--------------------------------

### par_lines example

Source: https://docs.rs/rayon/latest/rayon/str/trait.ParallelString.html?search=

Iterates over lines in parallel, excluding line endings. The example computes the length of each line.

```rust
use rayon::prelude::*;
let lengths: Vec<_> = "hello world\nfizbuzz"
    .par_lines()
    .map(|l| l.len())
    .collect();
assert_eq!(vec![11, 7], lengths);
```

--------------------------------

### par_sort_unstable_by examples

Source: https://docs.rs/rayon/latest/rayon/slice/trait.ParallelSliceMut.html?search=u32+-%3E+bool

Sorts a mutable slice in parallel using a comparator function. The comparator must define a total ordering. The first example sorts floats using partial_cmp, and the second example sorts integers in ascending and then descending order.

```rust
use rayon::prelude::*;

let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0];
floats.par_sort_unstable_by(|a, b| a.partial_cmp(b).unwrap());
assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]);
```

```rust
use rayon::prelude::*;

let mut v = [5, 4, 1, 3, 2];
v.par_sort_unstable_by(|a, b| a.cmp(b));
assert_eq!(v, [1, 2, 3, 4, 5]);

// reverse sorting
v.par_sort_unstable_by(|a, b| b.cmp(a));
assert_eq!(v, [5, 4, 3, 2, 1]);
```

--------------------------------

### par_matches example

Source: https://docs.rs/rayon/latest/rayon/str/trait.ParallelString.html?search=

Finds all substrings matching a predicate in parallel. The example sums numeric digits parsed from matches.

```rust
use rayon::prelude::*;
let total = "1, 2, buckle, 3, 4, door"
   .par_matches(char::is_numeric)
   .map(|s| s.parse::<i32>().expect("digit"))
   .sum();
assert_eq!(10, total);
```

--------------------------------

### Prefix ordering example tree

Source: https://docs.rs/rayon/latest/rayon/iter/fn.walk_tree_prefix.html?search=std%3A%3Avec

A diagram of a perfect binary tree of 7 nodes, used to illustrate the prefix ordering guarantee of walk_tree_prefix.

```text
     a
    / \
   /   \
  b     c
 / \   / \
d   e f   g

reduced as a,b,d,e,c,f,g
```

--------------------------------

### for_each_with example

Source: https://docs.rs/rayon/latest/rayon/iter/trait.ParallelIterator.html

Executes a closure with an initial value on each item in parallel. The init value is cloned as needed and does not need to be Sync. The example sends items through a channel and asserts the collected results.

```rust
use std::sync::mpsc::channel;
use rayon::prelude::*;

let (sender, receiver) = channel();

(0..5).into_par_iter().for_each_with(sender, |s, x| s.send(x).unwrap());

let mut res: Vec<_> = receiver.iter().collect();

res.sort();

assert_eq!(&res[..], &[0, 1, 2, 3, 4])
```

--------------------------------

### all example: check if all items match predicate

Source: https://docs.rs/rayon/latest/rayon/iter/trait.ParallelIterator.html

Returns true if every item matches the predicate. If a counter-example is found, processing stops and false is returned.

```rust
use rayon::prelude::*;

let a = [0, 12, 3, 4, 0, 23, 0];

let is_valid = a.par_iter().all(|&x| x > 10);

assert!(!is_valid);
```

--------------------------------

### par_match_indices example

Source: https://docs.rs/rayon/latest/rayon/str/trait.ParallelString.html?search=

Finds substrings matching a predicate along with their byte indices. The example collects digit matches and their positions.

```rust
use rayon::prelude::*;
let digits: Vec<_> = "1, 2, buckle, 3, 4, door"
   .par_match_indices(char::is_numeric)
   .collect();
assert_eq!(digits, vec![(0, "1"), (3, "2"), (14, "3"), (17, "4")]);
```

--------------------------------

### count example

Source: https://docs.rs/rayon/latest/rayon/iter/trait.ParallelIterator.html

Counts the number of items in the parallel iterator. The example counts 0 to 99 and asserts the result is 100.

```rust
use rayon::prelude::*;

let count = (0..100).into_par_iter().count();

assert_eq!(count, 100);
```
Tokens:
Raw