rayon/lib.rs
1#![doc(html_root_url = "https://docs.rs/rayon/1.5")]
2#![deny(missing_debug_implementations)]
3#![deny(missing_docs)]
4#![deny(unreachable_pub)]
5#![warn(rust_2018_idioms)]
6
7//! Data-parallelism library that makes it easy to convert sequential
8//! computations into parallel
9//!
10//! Rayon is lightweight and convenient for introducing parallelism into existing
11//! code. It guarantees data-race free executions and takes advantage of
12//! parallelism when sensible, based on work-load at runtime.
13//!
14//! # How to use Rayon
15//!
16//! There are two ways to use Rayon:
17//!
18//! - **High-level parallel constructs** are the simplest way to use Rayon and also
19//! typically the most efficient.
20//! - [Parallel iterators][iter module] make it easy to convert a sequential iterator to
21//! execute in parallel.
22//! - The [`ParallelIterator`] trait defines general methods for all parallel iterators.
23//! - The [`IndexedParallelIterator`] trait adds methods for iterators that support random
24//! access.
25//! - The [`par_sort`] method sorts `&mut [T]` slices (or vectors) in parallel.
26//! - [`par_extend`] can be used to efficiently grow collections with items produced
27//! by a parallel iterator.
28//! - **Custom tasks** let you divide your work into parallel tasks yourself.
29//! - [`join`] is used to subdivide a task into two pieces.
30//! - [`scope`] creates a scope within which you can create any number of parallel tasks.
31//! - [`ThreadPoolBuilder`] can be used to create your own thread pools or customize
32//! the global one.
33//!
34//! [iter module]: iter/index.html
35//! [`join`]: fn.join.html
36//! [`scope`]: fn.scope.html
37//! [`par_sort`]: slice/trait.ParallelSliceMut.html#method.par_sort
38//! [`par_extend`]: iter/trait.ParallelExtend.html#tymethod.par_extend
39//! [`ThreadPoolBuilder`]: struct.ThreadPoolBuilder.html
40//!
41//! # Basic usage and the Rayon prelude
42//!
43//! First, you will need to add `rayon` to your `Cargo.toml`.
44//!
45//! Next, to use parallel iterators or the other high-level methods,
46//! you need to import several traits. Those traits are bundled into
47//! the module [`rayon::prelude`]. It is recommended that you import
48//! all of these traits at once by adding `use rayon::prelude::*` at
49//! the top of each module that uses Rayon methods.
50//!
51//! These traits give you access to the `par_iter` method which provides
52//! parallel implementations of many iterative functions such as [`map`],
53//! [`for_each`], [`filter`], [`fold`], and [more].
54//!
55//! [`rayon::prelude`]: prelude/index.html
56//! [`map`]: iter/trait.ParallelIterator.html#method.map
57//! [`for_each`]: iter/trait.ParallelIterator.html#method.for_each
58//! [`filter`]: iter/trait.ParallelIterator.html#method.filter
59//! [`fold`]: iter/trait.ParallelIterator.html#method.fold
60//! [more]: iter/trait.ParallelIterator.html#provided-methods
61//! [`ParallelIterator`]: iter/trait.ParallelIterator.html
62//! [`IndexedParallelIterator`]: iter/trait.IndexedParallelIterator.html
63//!
64//! # Crate Layout
65//!
66//! Rayon extends many of the types found in the standard library with
67//! parallel iterator implementations. The modules in the `rayon`
68//! crate mirror [`std`] itself: so, e.g., the `option` module in
69//! Rayon contains parallel iterators for the `Option` type, which is
70//! found in [the `option` module of `std`]. Similarly, the
71//! `collections` module in Rayon offers parallel iterator types for
72//! [the `collections` from `std`]. You will rarely need to access
73//! these submodules unless you need to name iterator types
74//! explicitly.
75//!
76//! [the `option` module of `std`]: https://doc.rust-lang.org/std/option/index.html
77//! [the `collections` from `std`]: https://doc.rust-lang.org/std/collections/index.html
78//! [`std`]: https://doc.rust-lang.org/std/
79//!
80//! # Other questions?
81//!
82//! See [the Rayon FAQ][faq].
83//!
84//! [faq]: https://github.com/rayon-rs/rayon/blob/master/FAQ.md
85
86#[macro_use]
87mod delegate;
88
89#[macro_use]
90mod private;
91
92mod split_producer;
93
94pub mod array;
95pub mod collections;
96pub mod iter;
97pub mod option;
98pub mod prelude;
99pub mod range;
100pub mod range_inclusive;
101pub mod result;
102pub mod slice;
103pub mod str;
104pub mod string;
105pub mod vec;
106
107mod math;
108mod par_either;
109
110mod compile_fail;
111
112pub use rayon_core::FnContext;
113pub use rayon_core::ThreadBuilder;
114pub use rayon_core::ThreadPool;
115pub use rayon_core::ThreadPoolBuildError;
116pub use rayon_core::ThreadPoolBuilder;
117pub use rayon_core::{current_num_threads, current_thread_index};
118pub use rayon_core::{in_place_scope, scope, Scope};
119pub use rayon_core::{in_place_scope_fifo, scope_fifo, ScopeFifo};
120pub use rayon_core::{join, join_context};
121pub use rayon_core::{spawn, spawn_fifo};