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] 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` get(self) -> *mut T147 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> { clone(&self) -> Self154 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> {} 161