README.md
1# Rayon
2
3[](https://crates.io/crates/rayon)
4[](https://docs.rs/rayon)
5
6
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]: http://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.5"
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.36.0` or greater.
88
89## Contribution
90
91Rayon is an open source project! If you'd like to contribute to Rayon, check out [the list of "help wanted" issues](https://github.com/rayon-rs/rayon/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22). These are all (or should be) issues that are suitable for getting started, and they generally include a detailed set of instructions for what to do. Please ask questions if anything is unclear! Also, check out the [Guide to Development](https://github.com/rayon-rs/rayon/wiki/Guide-to-Development) page on the wiki. Note that all code submitted in PRs to Rayon is assumed to [be licensed under Rayon's dual MIT/Apache2 licensing](https://github.com/rayon-rs/rayon/blob/master/README.md#license).
92
93## Quick demo
94
95To see Rayon in action, check out the `rayon-demo` directory, which
96includes a number of demos of code using Rayon. For example, run this
97command to get a visualization of an nbody simulation. To see the
98effect of using Rayon, press `s` to run sequentially and `p` to run in
99parallel.
100
101```text
102> cd rayon-demo
103> cargo run --release -- nbody visualize
104```
105
106For more information on demos, try:
107
108```text
109> cd rayon-demo
110> cargo run --release -- --help
111```
112
113## Other questions?
114
115See [the Rayon FAQ][faq].
116
117[faq]: https://github.com/rayon-rs/rayon/blob/master/FAQ.md
118
119## License
120
121Rayon is distributed under the terms of both the MIT license and the
122Apache License (Version 2.0). See [LICENSE-APACHE](LICENSE-APACHE) and
123[LICENSE-MIT](LICENSE-MIT) for details. Opening a pull requests is
124assumed to signal agreement with these licensing terms.
125
){kind=link}
){kind=link}
){kind=link}
){kind=link}
){kind=link}