1#![deny(missing_debug_implementations)]
2#![deny(missing_docs)]
3#![deny(unreachable_pub)]
4#![warn(rust_2018_idioms)]
5
6//! Data-parallelism library that makes it easy to convert sequential
7//! computations into parallel
8//!
9//! Rayon is lightweight and convenient for introducing parallelism into existing
10//! code. It guarantees data-race free executions and takes advantage of
11//! parallelism when sensible, based on work-load at runtime.
12//!
13//! # How to use Rayon
14//!
15//! There are two ways to use Rayon:
16//!
17//! - **High-level parallel constructs** are the simplest way to use Rayon and also
18//! typically the most efficient.
19//! - [Parallel iterators][iter module] make it easy to convert a sequential iterator to
20//! execute in parallel.
21//! - The [`ParallelIterator`] trait defines general methods for all parallel iterators.
22//! - The [`IndexedParallelIterator`] trait adds methods for iterators that support random
23//! access.
24//! - The [`par_sort`] method sorts `&mut [T]` slices (or vectors) in parallel.
25//! - [`par_extend`] can be used to efficiently grow collections with items produced
26//! by a parallel iterator.
27//! - **Custom tasks** let you divide your work into parallel tasks yourself.
28//! - [`join`] is used to subdivide a task into two pieces.
29//! - [`scope`] creates a scope within which you can create any number of parallel tasks.
30//! - [`ThreadPoolBuilder`] can be used to create your own thread pools or customize
31//! the global one.
32//!
33//! [iter module]: iter/index.html
34//! [`join`]: fn.join.html
35//! [`scope`]: fn.scope.html
36//! [`par_sort`]: slice/trait.ParallelSliceMut.html#method.par_sort
37//! [`par_extend`]: iter/trait.ParallelExtend.html#tymethod.par_extend
38//! [`ThreadPoolBuilder`]: struct.ThreadPoolBuilder.html
39//!
40//! # Basic usage and the Rayon prelude
41//!
42//! First, you will need to add `rayon` to your `Cargo.toml`.
43//!
44//! Next, to use parallel iterators or the other high-level methods,
45//! you need to import several traits. Those traits are bundled into
46//! the module [`rayon::prelude`]. It is recommended that you import
47//! all of these traits at once by adding `use rayon::prelude::*` at
48//! the top of each module that uses Rayon methods.
49//!
50//! These traits give you access to the `par_iter` method which provides
51//! parallel implementations of many iterative functions such as [`map`],
52//! [`for_each`], [`filter`], [`fold`], and [more].
53//!
54//! [`rayon::prelude`]: prelude/index.html
55//! [`map`]: iter/trait.ParallelIterator.html#method.map
56//! [`for_each`]: iter/trait.ParallelIterator.html#method.for_each
57//! [`filter`]: iter/trait.ParallelIterator.html#method.filter
58//! [`fold`]: iter/trait.ParallelIterator.html#method.fold
59//! [more]: iter/trait.ParallelIterator.html#provided-methods
60//! [`ParallelIterator`]: iter/trait.ParallelIterator.html
61//! [`IndexedParallelIterator`]: iter/trait.IndexedParallelIterator.html
62//!
63//! # Crate Layout
64//!
65//! Rayon extends many of the types found in the standard library with
66//! parallel iterator implementations. The modules in the `rayon`
67//! crate mirror [`std`] itself: so, e.g., the `option` module in
68//! Rayon contains parallel iterators for the `Option` type, which is
69//! found in [the `option` module of `std`]. Similarly, the
70//! `collections` module in Rayon offers parallel iterator types for
71//! [the `collections` from `std`]. You will rarely need to access
72//! these submodules unless you need to name iterator types
73//! explicitly.
74//!
75//! [the `option` module of `std`]: https://doc.rust-lang.org/std/option/index.html
76//! [the `collections` from `std`]: https://doc.rust-lang.org/std/collections/index.html
77//! [`std`]: https://doc.rust-lang.org/std/
78//!
79//! # Targets without threading
80//!
81//! Rayon has limited support for targets without `std` threading implementations.
82//! See the [`rayon_core`] documentation for more information about its global fallback.
83//!
84//! # Other questions?
85//!
86//! See [the Rayon FAQ][faq].
87//!
88//! [faq]: https://github.com/rayon-rs/rayon/blob/master/FAQ.md
89
90#[macro_use]
91mod delegate;
92
93#[macro_use]
94mod private;
95
96mod split_producer;
97
98pub mod array;
99pub mod collections;
100pub mod iter;
101pub mod option;
102pub mod prelude;
103pub mod range;
104pub mod range_inclusive;
105pub mod result;
106pub mod slice;
107pub mod str;
108pub mod string;
109pub mod vec;
110
111mod math;
112mod par_either;
113
114mod compile_fail;
115
116pub use rayon_core::FnContext;
117pub use rayon_core::ThreadBuilder;
118pub use rayon_core::ThreadPool;
119pub use rayon_core::ThreadPoolBuildError;
120pub use rayon_core::ThreadPoolBuilder;
121pub use rayon_core::{broadcast, spawn_broadcast, BroadcastContext};
122pub use rayon_core::{current_num_threads, current_thread_index, max_num_threads};
123pub use rayon_core::{in_place_scope, scope, Scope};
124pub use rayon_core::{in_place_scope_fifo, scope_fifo, ScopeFifo};
125pub use rayon_core::{join, join_context};
126pub use rayon_core::{spawn, spawn_fifo};
127pub use rayon_core::{yield_local, yield_now, Yield};
128
129/// We need to transmit raw pointers across threads. It is possible to do this
130/// without any unsafe code by converting pointers to usize or to AtomicPtr<T>
131/// then back to a raw pointer for use. We prefer this approach because code
132/// that uses this type is more explicit.
133///
134/// Unsafe code is still required to dereference the pointer, so this type is
135/// not unsound on its own, although it does partly lift the unconditional
136/// !Send and !Sync on raw pointers. As always, dereference with care.
137struct SendPtr<T>(*mut T);
138
139// SAFETY: !Send for raw pointers is not for safety, just as a lint
140unsafe impl<T: Send> Send for SendPtr<T> {}
141
142// SAFETY: !Sync for raw pointers is not for safety, just as a lint
143unsafe impl<T: Send> Sync for SendPtr<T> {}
144
145impl<T> SendPtr<T> {
146 // Helper to avoid disjoint captures of `send_ptr.0`
147 fn get(self) -> *mut T {
148 self.0
149 }
150}
151
152// Implement Clone without the T: Clone bound from the derive
153impl<T> Clone for SendPtr<T> {
154 fn clone(&self) -> Self {
155 *self
156 }
157}
158
159// Implement Copy without the T: Copy bound from the derive
160impl<T> Copy for SendPtr<T> {}
161