README.md
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
9Rayon is a data-parallelism library for Rust. It is extremely
10lightweight and makes it easy to convert a sequential computation into
11a parallel one. It also guarantees data-race freedom. (You may also
12enjoy [this blog post][blog] about Rayon, which gives more background
13and details about how it works, or [this video][video], from the Rust
14Belt 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
23Rayon makes it drop-dead simple to convert sequential iterators into
24parallel ones: usually, you just change your `foo.iter()` call into
25`foo.par_iter()`, and Rayon does the rest:
26
27```rust
28use rayon::prelude::*;
29fn 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
37into tasks; it will dynamically adapt for maximum performance. If you
38need more flexibility than that, Rayon also offers the [join] and
39[scope] functions, which let you create parallel tasks on your own.
40For even more control, you can create [custom threadpools] rather than
41using 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
50You may have heard that parallel execution can produce all kinds of
51crazy bugs. Well, rest easy. Rayon's APIs all guarantee **data-race
52freedom**, which generally rules out most parallel bugs (though not
53all). In other words, **if your code compiles**, it typically does the
54same thing it did before.
55
56For the most, parallel iterators in particular are guaranteed to
57produce the same results as their sequential counterparts. One caveat:
58If your iterator has side effects (for example, sending methods to
59other threads through a [Rust channel] or writing to disk), those side
60effects may occur in a different order. Note also that, in some cases,
61parallel iterators offer alternative versions of the sequential
62iterator 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
69recommended way to use it is to add a line into your Cargo.toml such
70as:
71
72```toml
73[dependencies]
74rayon = "1.8"
75```
76
77To use the parallel iterator APIs, a number of traits have to be in
78scope. 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
80each module where you would like to use the parallel iterator APIs,
81just add:
82
83```rust
84use rayon::prelude::*;
85```
86
87Rayon currently requires `rustc 1.63.0` or greater.
88
89### Usage with WebAssembly
90
91Rayon can work on the Web via WebAssembly, but requires an adapter and
92some project configuration to account for differences between
93WebAssembly threads and threads on the other platforms.
94
95Check out the
96[wasm-bindgen-rayon](https://github.com/GoogleChromeLabs/wasm-bindgen-rayon)
97docs for more details.
98
99## Contribution
100
101Rayon is an open source project! If you'd like to contribute to Rayon,
102check out
103[the list of "help wanted" issues](https://github.com/rayon-rs/rayon/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22).
104These are all (or should be) issues that are suitable for getting
105started, and they generally include a detailed set of instructions for
106what to do. Please ask questions if anything is unclear! Also, check
107out the
108[Guide to Development](https://github.com/rayon-rs/rayon/wiki/Guide-to-Development)
109page on the wiki. Note that all code submitted in PRs to Rayon is
110assumed to
111[be licensed under Rayon's dual MIT/Apache 2.0 licensing](https://github.com/rayon-rs/rayon/blob/master/README.md#license).
112
113## Quick demo
114
115To see Rayon in action, check out the `rayon-demo` directory, which
116includes a number of demos of code using Rayon. For example, run this
117command to get a visualization of an N-body simulation. To see the
118effect of using Rayon, press `s` to run sequentially and `p` to run in
119parallel.
120
121```text
122> cd rayon-demo
123> cargo run --release -- nbody visualize
124```
125
126For more information on demos, try:
127
128```text
129> cd rayon-demo
130> cargo run --release -- --help
131```
132
133## Other questions?
134
135See [the Rayon FAQ][faq].
136
137[faq]: https://github.com/rayon-rs/rayon/blob/master/FAQ.md
138
139## License
140
141Rayon is distributed under the terms of both the MIT license and the
142Apache License (Version 2.0). See [LICENSE-APACHE](LICENSE-APACHE) and
143[LICENSE-MIT](LICENSE-MIT) for details. Opening a pull request is
144assumed to signal agreement with these licensing terms.
145
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}