| 1 |
# Rayon |
| 2 |
|
| 3 |
[](https://crates.io/crates/rayon) |
| 4 |
[](https://docs.rs/rayon) |
| 5 |
 |
| 6 |
[](https://github.com/rayon-rs/rayon/actions) |
| 7 |
[](https://gitter.im/rayon-rs/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) |
| 8 |
|
| 9 |
Rayon is a data-parallelism library for Rust. It is extremely |
| 10 |
lightweight and makes it easy to convert a sequential computation into |
| 11 |
a parallel one. It also guarantees data-race freedom. (You may also |
| 12 |
enjoy [this blog post][blog] about Rayon, which gives more background |
| 13 |
and details about how it works, or [this video][video], from the Rust |
| 14 |
Belt Rust conference.) Rayon is |
| 15 |
[available on crates.io](https://crates.io/crates/rayon), and |
| 16 |
[API documentation is available on docs.rs](https://docs.rs/rayon). |
| 17 |
|
| 18 |
[blog]: https://smallcultfollowing.com/babysteps/blog/2015/12/18/rayon-data-parallelism-in-rust/ |
| 19 |
[video]: https://www.youtube.com/watch?v=gof_OEv71Aw |
| 20 |
|
| 21 |
## Parallel iterators and more |
| 22 |
|
| 23 |
Rayon makes it drop-dead simple to convert sequential iterators into |
| 24 |
parallel ones: usually, you just change your `foo.iter()` call into |
| 25 |
`foo.par_iter()`, and Rayon does the rest: |
| 26 |
|
| 27 |
```rust |
| 28 |
use rayon::prelude::*; |
| 29 |
fn sum_of_squares(input: &[i32]) -> i32 { |
| 30 |
input.par_iter() // <-- just change that! |
| 31 |
.map(|&i| i * i) |
| 32 |
.sum() |
| 33 |
} |
| 34 |
``` |
| 35 |
|
| 36 |
[Parallel iterators] take care of deciding how to divide your data |
| 37 |
into tasks; it will dynamically adapt for maximum performance. If you |
| 38 |
need more flexibility than that, Rayon also offers the [join] and |
| 39 |
[scope] functions, which let you create parallel tasks on your own. |
| 40 |
For even more control, you can create [custom threadpools] rather than |
| 41 |
using Rayon's default, global threadpool. |
| 42 |
|
| 43 |
[Parallel iterators]: https://docs.rs/rayon/*/rayon/iter/index.html |
| 44 |
[join]: https://docs.rs/rayon/*/rayon/fn.join.html |
| 45 |
[scope]: https://docs.rs/rayon/*/rayon/fn.scope.html |
| 46 |
[custom threadpools]: https://docs.rs/rayon/*/rayon/struct.ThreadPool.html |
| 47 |
|
| 48 |
## No data races |
| 49 |
|
| 50 |
You may have heard that parallel execution can produce all kinds of |
| 51 |
crazy bugs. Well, rest easy. Rayon's APIs all guarantee **data-race |
| 52 |
freedom**, which generally rules out most parallel bugs (though not |
| 53 |
all). In other words, **if your code compiles**, it typically does the |
| 54 |
same thing it did before. |
| 55 |
|
| 56 |
For the most, parallel iterators in particular are guaranteed to |
| 57 |
produce the same results as their sequential counterparts. One caveat: |
| 58 |
If your iterator has side effects (for example, sending methods to |
| 59 |
other threads through a [Rust channel] or writing to disk), those side |
| 60 |
effects may occur in a different order. Note also that, in some cases, |
| 61 |
parallel iterators offer alternative versions of the sequential |
| 62 |
iterator methods that can have higher performance. |
| 63 |
|
| 64 |
[Rust channel]: https://doc.rust-lang.org/std/sync/mpsc/fn.channel.html |
| 65 |
|
| 66 |
## Using Rayon |
| 67 |
|
| 68 |
[Rayon is available on crates.io](https://crates.io/crates/rayon). The |
| 69 |
recommended way to use it is to add a line into your Cargo.toml such |
| 70 |
as: |
| 71 |
|
| 72 |
```toml |
| 73 |
[dependencies] |
| 74 |
rayon = "1.8" |
| 75 |
``` |
| 76 |
|
| 77 |
To use the parallel iterator APIs, a number of traits have to be in |
| 78 |
scope. The easiest way to bring those things into scope is to use the |
| 79 |
[Rayon prelude](https://docs.rs/rayon/*/rayon/prelude/index.html). In |
| 80 |
each module where you would like to use the parallel iterator APIs, |
| 81 |
just add: |
| 82 |
|
| 83 |
```rust |
| 84 |
use rayon::prelude::*; |
| 85 |
``` |
| 86 |
|
| 87 |
Rayon currently requires `rustc 1.63.0` or greater. |
| 88 |
|
| 89 |
### Usage with WebAssembly |
| 90 |
|
| 91 |
By default, when building to WebAssembly, Rayon will treat it as any |
| 92 |
other platform without multithreading support and will fall back to |
| 93 |
sequential iteration. This allows existing code to compile and run |
| 94 |
successfully with no changes necessary, but it will run slower as it |
| 95 |
will only use a single CPU core. |
| 96 |
|
| 97 |
You can build Rayon-based projects with proper multithreading support |
| 98 |
for the Web, but you'll need an adapter and some project configuration |
| 99 |
to account for differences between WebAssembly threads and threads |
| 100 |
on the other platforms. |
| 101 |
|
| 102 |
Check out the |
| 103 |
[wasm-bindgen-rayon](https://github.com/RReverser/wasm-bindgen-rayon) |
| 104 |
docs for more details. |
| 105 |
|
| 106 |
## Contribution |
| 107 |
|
| 108 |
Rayon is an open source project! If you'd like to contribute to Rayon, |
| 109 |
check out |
| 110 |
[the list of "help wanted" issues](https://github.com/rayon-rs/rayon/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22). |
| 111 |
These are all (or should be) issues that are suitable for getting |
| 112 |
started, and they generally include a detailed set of instructions for |
| 113 |
what to do. Please ask questions if anything is unclear! Also, check |
| 114 |
out the |
| 115 |
[Guide to Development](https://github.com/rayon-rs/rayon/wiki/Guide-to-Development) |
| 116 |
page on the wiki. Note that all code submitted in PRs to Rayon is |
| 117 |
assumed to |
| 118 |
[be licensed under Rayon's dual MIT/Apache 2.0 licensing](https://github.com/rayon-rs/rayon/blob/main/README.md#license). |
| 119 |
|
| 120 |
## Quick demo |
| 121 |
|
| 122 |
To see Rayon in action, check out the `rayon-demo` directory, which |
| 123 |
includes a number of demos of code using Rayon. For example, run this |
| 124 |
command to get a visualization of an N-body simulation. To see the |
| 125 |
effect of using Rayon, press `s` to run sequentially and `p` to run in |
| 126 |
parallel. |
| 127 |
|
| 128 |
```text |
| 129 |
> cd rayon-demo |
| 130 |
> cargo run --release -- nbody visualize |
| 131 |
``` |
| 132 |
|
| 133 |
For more information on demos, try: |
| 134 |
|
| 135 |
```text |
| 136 |
> cd rayon-demo |
| 137 |
> cargo run --release -- --help |
| 138 |
``` |
| 139 |
|
| 140 |
## Other questions? |
| 141 |
|
| 142 |
See [the Rayon FAQ][faq]. |
| 143 |
|
| 144 |
[faq]: https://github.com/rayon-rs/rayon/blob/main/FAQ.md |
| 145 |
|
| 146 |
## License |
| 147 |
|
| 148 |
Rayon is distributed under the terms of both the MIT license and the |
| 149 |
Apache License (Version 2.0). See [LICENSE-APACHE](LICENSE-APACHE) and |
| 150 |
[LICENSE-MIT](LICENSE-MIT) for details. Opening a pull request is |
| 151 |
assumed to signal agreement with these licensing terms. |