Debian Codegraph @

.cargo/vendor/rayon/README.md

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