| 1 |
#![deny(missing_debug_implementations)] |
| 2 |
#![deny(missing_docs)] |
| 3 |
#![deny(unreachable_pub)] |
| 4 |
#![warn(rust_2018_idioms)] |
| 5 |
|
| 6 |
//! Rayon is a data-parallelism library that makes it easy to convert sequential |
| 7 |
//! computations into parallel. |
| 8 |
//! |
| 9 |
//! It 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/main/FAQ.md |
| 89 |
|
| 90 |
#[macro_use] |
| 91 |
mod delegate; |
| 92 |
|
| 93 |
#[macro_use] |
| 94 |
mod private; |
| 95 |
|
| 96 |
mod split_producer; |
| 97 |
|
| 98 |
pub mod array; |
| 99 |
pub mod collections; |
| 100 |
pub mod iter; |
| 101 |
pub mod option; |
| 102 |
pub mod prelude; |
| 103 |
pub mod range; |
| 104 |
pub mod range_inclusive; |
| 105 |
pub mod result; |
| 106 |
pub mod slice; |
| 107 |
pub mod str; |
| 108 |
pub mod string; |
| 109 |
pub mod vec; |
| 110 |
|
| 111 |
mod math; |
| 112 |
mod par_either; |
| 113 |
|
| 114 |
mod compile_fail; |
| 115 |
|
| 116 |
pub use rayon_core::FnContext; |
| 117 |
pub use rayon_core::ThreadBuilder; |
| 118 |
pub use rayon_core::ThreadPool; |
| 119 |
pub use rayon_core::ThreadPoolBuildError; |
| 120 |
pub use rayon_core::ThreadPoolBuilder; |
| 121 |
pub use rayon_core::{broadcast, spawn_broadcast, BroadcastContext}; |
| 122 |
pub use rayon_core::{current_num_threads, current_thread_index, max_num_threads}; |
| 123 |
pub use rayon_core::{in_place_scope, scope, Scope}; |
| 124 |
pub use rayon_core::{in_place_scope_fifo, scope_fifo, ScopeFifo}; |
| 125 |
pub use rayon_core::{join, join_context}; |
| 126 |
pub use rayon_core::{spawn, spawn_fifo}; |
| 127 |
pub 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. |
| 137 |
struct SendPtr<T>(*mut T); |
| 138 |
|
| 139 |
// SAFETY: !Send for raw pointers is not for safety, just as a lint |
| 140 |
unsafe impl<T: Send> Send for SendPtr<T> {} |
| 141 |
|
| 142 |
// SAFETY: !Sync for raw pointers is not for safety, just as a lint |
| 143 |
unsafe impl<T: Send> Sync for SendPtr<T> {} |
| 144 |
|
| 145 |
impl<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 |
| 153 |
impl<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 |
| 160 |
impl<T> Copy for SendPtr<T> {} |