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
91By default, when building to WebAssembly, Rayon will treat it as any
92other platform without multithreading support and will fall back to
93sequential iteration. This allows existing code to compile and run
94successfully with no changes necessary, but it will run slower as it
95will only use a single CPU core.
96
97You can build Rayon-based projects with proper multithreading support
98for the Web, but you'll need an adapter and some project configuration
99to account for differences between WebAssembly threads and threads
100on the other platforms.
101
102Check out the
103[wasm-bindgen-rayon](https://github.com/RReverser/wasm-bindgen-rayon)
104docs for more details.
105
106## Contribution
107
108Rayon is an open source project! If you'd like to contribute to Rayon,
109check 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).
111These are all (or should be) issues that are suitable for getting
112started, and they generally include a detailed set of instructions for
113what to do. Please ask questions if anything is unclear! Also, check
114out the
115[Guide to Development](https://github.com/rayon-rs/rayon/wiki/Guide-to-Development)
116page on the wiki. Note that all code submitted in PRs to Rayon is
117assumed 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
122To see Rayon in action, check out the `rayon-demo` directory, which
123includes a number of demos of code using Rayon. For example, run this
124command to get a visualization of an N-body simulation. To see the
125effect of using Rayon, press `s` to run sequentially and `p` to run in
126parallel.
127
128```text
129> cd rayon-demo
130> cargo run --release -- nbody visualize
131```
132
133For more information on demos, try:
134
135```text
136> cd rayon-demo
137> cargo run --release -- --help
138```
139
140## Other questions?
141
142See [the Rayon FAQ][faq].
143
144[faq]: https://github.com/rayon-rs/rayon/blob/main/FAQ.md
145
146## License
147
148Rayon is distributed under the terms of both the MIT license and the
149Apache License (Version 2.0). See [LICENSE-APACHE](LICENSE-APACHE) and
150[LICENSE-MIT](LICENSE-MIT) for details. Opening a pull request is
151assumed to signal agreement with these licensing terms.
152
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}