third_party/rust/rayon/README.md

   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.56](https://img.shields.io/badge/rustc-1.56+-red.svg)
   6 [![build status](https://github.com/rayon-rs/rayon/workflows/master/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.5"
  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.56.0` or greater.
  88
  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
  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
 110 ```text
 111 > cd rayon-demo
 112 > cargo run --release -- nbody visualize
 113 ```
 114
 115 For more information on demos, try:
 116
 117 ```text
 118 > cd rayon-demo
 119 > cargo run --release -- --help
 120 ```
 121
 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 request is
 133 assumed to signal agreement with these licensing terms.