|
1 |
| -# Rayon |
| 1 | +# rustc-rayon |
2 | 2 |
|
3 |
| -[](https://crates.io/crates/rayon) |
4 |
| -[](https://docs.rs/rayon) |
5 |
| -[](https://travis-ci.org/rayon-rs/rayon) |
6 |
| -[](https://ci.appveyor.com/project/cuviper/rayon/branch/master) |
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]: 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 |
| - |
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.1" |
75 |
| -``` |
76 |
| - |
77 |
| -and then add the following to your `lib.rs`: |
78 |
| - |
79 |
| -```rust |
80 |
| -extern crate rayon; |
81 |
| -``` |
82 |
| - |
83 |
| -To use the Parallel Iterator APIs, a number of traits have to be in |
84 |
| -scope. The easiest way to bring those things into scope is to use the |
85 |
| -[Rayon prelude](https://docs.rs/rayon/*/rayon/prelude/index.html). In |
86 |
| -each module where you would like to use the parallel iterator APIs, |
87 |
| -just add: |
88 |
| - |
89 |
| -```rust |
90 |
| -use rayon::prelude::*; |
91 |
| -``` |
92 |
| - |
93 |
| -Rayon currently requires `rustc 1.28.0` or greater. |
94 |
| - |
95 |
| -## Contribution |
96 |
| - |
97 |
| -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). |
98 |
| - |
99 |
| -## Quick demo |
100 |
| - |
101 |
| -To see Rayon in action, check out the `rayon-demo` directory, which |
102 |
| -includes a number of demos of code using Rayon. For example, run this |
103 |
| -command to get a visualization of an nbody simulation. To see the |
104 |
| -effect of using Rayon, press `s` to run sequentially and `p` to run in |
105 |
| -parallel. |
106 |
| - |
107 |
| -```text |
108 |
| -> cd rayon-demo |
109 |
| -> cargo run --release -- nbody visualize |
110 |
| -``` |
111 |
| - |
112 |
| -For more information on demos, try: |
113 |
| - |
114 |
| -```text |
115 |
| -> cd rayon-demo |
116 |
| -> cargo run --release -- --help |
117 |
| -``` |
118 |
| - |
119 |
| -## Other questions? |
120 |
| - |
121 |
| -See [the Rayon FAQ][faq]. |
122 |
| - |
123 |
| -[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. =) |
124 | 4 |
|
125 | 5 | ## License
|
126 | 6 |
|
127 |
| -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 |
128 | 8 | Apache License (Version 2.0). See [LICENSE-APACHE](LICENSE-APACHE) and
|
129 | 9 | [LICENSE-MIT](LICENSE-MIT) for details. Opening a pull requests is
|
130 | 10 | assumed to signal agreement with these licensing terms.
|
0 commit comments