]>
Commit | Line | Data |
---|---|---|
2c00a5a8 XL |
1 | # Rayon |
2 | ||
3 | [![Rayon crate](https://img.shields.io/crates/v/rayon.svg)](https://crates.io/crates/rayon) | |
4 | [![Rayon documentation](https://docs.rs/rayon/badge.svg)](https://docs.rs/rayon) | |
5869c6ff | 5 | ![minimum rustc 1.36](https://img.shields.io/badge/rustc-1.36+-red.svg) |
17df50a5 | 6 | [![build status](https://github.com/rayon-rs/rayon/workflows/master/badge.svg)](https://github.com/rayon-rs/rayon/actions) |
2c00a5a8 XL |
7 | [![Join the chat at https://gitter.im/rayon-rs/Lobby](https://badges.gitter.im/rayon-rs/Lobby.svg)](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 | ||
17df50a5 | 18 | [blog]: https://smallcultfollowing.com/babysteps/blog/2015/12/18/rayon-data-parallelism-in-rust/ |
2c00a5a8 XL |
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 | |
416331ca | 57 | produce the same results as their sequential counterparts. One caveat: |
2c00a5a8 XL |
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] | |
5869c6ff | 74 | rayon = "1.5" |
2c00a5a8 XL |
75 | ``` |
76 | ||
2c00a5a8 XL |
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 | ||
5869c6ff | 87 | Rayon currently requires `rustc 1.36.0` or greater. |
2c00a5a8 | 88 | |
04454e1e FG |
89 | ### Usage with WebAssembly |
90 | ||
91 | Rayon can work on the Web via WebAssembly, but requires an adapter | |
92 | and some project configuration to account for differences between | |
93 | WebAssembly threads and threads on the other platforms. | |
94 | ||
95 | Check out [wasm-bindgen-rayon](https://github.com/GoogleChromeLabs/wasm-bindgen-rayon) | |
96 | docs for more details. | |
97 | ||
2c00a5a8 XL |
98 | ## Contribution |
99 | ||
100 | Rayon 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). | |
101 | ||
102 | ## Quick demo | |
103 | ||
104 | To see Rayon in action, check out the `rayon-demo` directory, which | |
105 | includes a number of demos of code using Rayon. For example, run this | |
106 | command to get a visualization of an nbody simulation. To see the | |
107 | effect of using Rayon, press `s` to run sequentially and `p` to run in | |
108 | parallel. | |
109 | ||
416331ca | 110 | ```text |
2c00a5a8 | 111 | > cd rayon-demo |
416331ca | 112 | > cargo run --release -- nbody visualize |
2c00a5a8 XL |
113 | ``` |
114 | ||
115 | For more information on demos, try: | |
116 | ||
416331ca | 117 | ```text |
2c00a5a8 | 118 | > cd rayon-demo |
416331ca | 119 | > cargo run --release -- --help |
2c00a5a8 XL |
120 | ``` |
121 | ||
2c00a5a8 XL |
122 | ## Other questions? |
123 | ||
124 | See [the Rayon FAQ][faq]. | |
125 | ||
126 | [faq]: https://github.com/rayon-rs/rayon/blob/master/FAQ.md | |
127 | ||
128 | ## License | |
129 | ||
130 | Rayon is distributed under the terms of both the MIT license and the | |
131 | Apache License (Version 2.0). See [LICENSE-APACHE](LICENSE-APACHE) and | |
132 | [LICENSE-MIT](LICENSE-MIT) for details. Opening a pull requests is | |
133 | assumed to signal agreement with these licensing terms. |