Repository files navigation

Rayon is a data-parallelism library for Rust. It is extremelylightweight and makes it easy to convert a sequential computation intoa parallel one. It also guarantees data-race freedom. (You may alsoenjoythis blog post about Rayon, which gives more backgroundand details about how it works, orthis video, from the RustBelt Rust conference.) Rayon isavailable on crates.io, andAPI documentation is available on docs.rs.

Rayon makes it drop-dead simple to convert sequential iterators intoparallel ones: usually, you just change yourfoo.iter() call intofoo.par_iter(), and Rayon does the rest:

use rayon::prelude::*;fnsum_of_squares(input:&[i32]) ->i32{    input.par_iter()// <-- just change that!.map(|&i| i* i).sum()}

Parallel iterators take care of deciding how to divide your datainto tasks; it will dynamically adapt for maximum performance. If youneed more flexibility than that, Rayon also offers thejoin andscope functions, which let you create parallel tasks on your own.For even more control, you can createcustom threadpools rather thanusing Rayon's default, global threadpool.

You may have heard that parallel execution can produce all kinds ofcrazy bugs. Well, rest easy. Rayon's APIs all guaranteedata-racefreedom, which generally rules out most parallel bugs (though notall). In other words,if your code compiles, it typically does thesame thing it did before.

For the most, parallel iterators in particular are guaranteed toproduce the same results as their sequential counterparts. One caveat:If your iterator has side effects (for example, sending methods toother threads through aRust channel or writing to disk), those sideeffects may occur in a different order. Note also that, in some cases,parallel iterators offer alternative versions of the sequentialiterator methods that can have higher performance.

Rayon is available on crates.io. Therecommended way to use it is to add a line into your Cargo.toml suchas:

[dependencies]rayon ="1.10"

To use the parallel iterator APIs, a number of traits have to be inscope. The easiest way to bring those things into scope is to use theRayon prelude. Ineach module where you would like to use the parallel iterator APIs,just add:

use rayon::prelude::*;

Rayon currently requiresrustc 1.63.0 or greater.

By default, when building to WebAssembly, Rayon will treat it as anyother platform without multithreading support and will fall back tosequential iteration. This allows existing code to compile and runsuccessfully with no changes necessary, but it will run slower as itwill only use a single CPU core.

You can build Rayon-based projects with proper multithreading supportfor the Web, but you'll need an adapter and some project configurationto account for differences between WebAssembly threads and threads onthe other platforms.

Check out thewasm-bindgen-rayondocs for more details.

Rayon is an open source project! If you'd like to contribute to Rayon,check outthe list of "help wanted" issues.These are all (or should be) issues that are suitable for gettingstarted, and they generally include a detailed set of instructions forwhat to do. Please ask questions if anything is unclear! Also, checkout theGuide to Developmentpage on the wiki. Note that all code submitted in PRs to Rayon isassumed tobe licensed under Rayon's dual MIT/Apache 2.0 licensing.

To see Rayon in action, check out therayon-demo directory, whichincludes a number of demos of code using Rayon. For example, run thiscommand to get a visualization of an N-body simulation. To see theeffect of using Rayon, presss to run sequentially andp to run inparallel.

> cd rayon-demo> cargo run --release -- nbody visualize

For more information on demos, try:

> cd rayon-demo> cargo run --release -- --help

Seethe Rayon FAQ.

Rayon is distributed under the terms of both the MIT license and theApache License (Version 2.0). SeeLICENSE-APACHE andLICENSE-MIT for details. Opening a pull request isassumed to signal agreement with these licensing terms.