|
1 | | -# Rayon |
| 1 | +# rustc-rayon |
2 | 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.7" |
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.59.0` or greater. |
88 | | - |
89 | | -### Usage with WebAssembly |
90 | | - |
91 | | -Rayon can work on the Web via WebAssembly, but requires an adapter and |
92 | | -some project configuration to account for differences between |
93 | | -WebAssembly threads and threads on the other platforms. |
94 | | - |
95 | | -Check out the |
96 | | -[wasm-bindgen-rayon](https://github.com/GoogleChromeLabs/wasm-bindgen-rayon) |
97 | | -docs for more details. |
98 | | - |
99 | | -## Contribution |
100 | | - |
101 | | -Rayon is an open source project! If you'd like to contribute to Rayon, |
102 | | -check 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). |
104 | | -These are all (or should be) issues that are suitable for getting |
105 | | -started, and they generally include a detailed set of instructions for |
106 | | -what to do. Please ask questions if anything is unclear! Also, check |
107 | | -out the |
108 | | -[Guide to Development](https://github.com/rayon-rs/rayon/wiki/Guide-to-Development) |
109 | | -page on the wiki. Note that all code submitted in PRs to Rayon is |
110 | | -assumed 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 | | - |
115 | | -To see Rayon in action, check out the `rayon-demo` directory, which |
116 | | -includes a number of demos of code using Rayon. For example, run this |
117 | | -command to get a visualization of an N-body simulation. To see the |
118 | | -effect of using Rayon, press `s` to run sequentially and `p` to run in |
119 | | -parallel. |
120 | | - |
121 | | -```text |
122 | | -> cd rayon-demo |
123 | | -> cargo run --release -- nbody visualize |
124 | | -``` |
125 | | - |
126 | | -For more information on demos, try: |
127 | | - |
128 | | -```text |
129 | | -> cd rayon-demo |
130 | | -> cargo run --release -- --help |
131 | | -``` |
132 | | - |
133 | | -## Other questions? |
134 | | - |
135 | | -See [the Rayon FAQ][faq]. |
136 | | - |
137 | | -[faq]: https://github.com/rayon-rs/rayon/blob/master/FAQ.md |
| 3 | +rustc-rayon is a fork of [the Rayon crate](https://github.com/rayon-rs/rayon/). It adds a few "in progress" features that rustc is using, mostly around deadlock detection. These features are not stable and should not be used by others -- though they may find their way into rayon proper at some point. In general, if you are not rustc, you should be using the real rayon crate, not rustc-rayon. =) |
138 | 4 |
|
139 | 5 | ## License |
140 | 6 |
|
141 | | -Rayon is distributed under the terms of both the MIT license and the |
| 7 | +rustc-rayon is a fork of rayon. rayon is distributed under the terms of both the MIT license and the |
142 | 8 | Apache License (Version 2.0). See [LICENSE-APACHE](LICENSE-APACHE) and |
143 | 9 | [LICENSE-MIT](LICENSE-MIT) for details. Opening a pull request is |
144 | 10 | assumed to signal agreement with these licensing terms. |
0 commit comments