]>
Commit | Line | Data |
---|---|---|
2c00a5a8 | 1 | #![deny(missing_debug_implementations)] |
2c00a5a8 | 2 | #![deny(missing_docs)] |
416331ca | 3 | #![deny(unreachable_pub)] |
1b1a35ee | 4 | #![warn(rust_2018_idioms)] |
2c00a5a8 XL |
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. | |
f035d41b XL |
21 | //! - The [`ParallelIterator`] trait defines general methods for all parallel iterators. |
22 | //! - The [`IndexedParallelIterator`] trait adds methods for iterators that support random | |
23 | //! access. | |
2c00a5a8 XL |
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 | //! | |
83c7162d | 33 | //! [iter module]: iter/index.html |
2c00a5a8 XL |
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 | //! | |
f035d41b | 42 | //! First, you will need to add `rayon` to your `Cargo.toml`. |
2c00a5a8 XL |
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 | //! | |
416331ca | 54 | //! [`rayon::prelude`]: prelude/index.html |
2c00a5a8 XL |
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 | |
f035d41b XL |
60 | //! [`ParallelIterator`]: iter/trait.ParallelIterator.html |
61 | //! [`IndexedParallelIterator`]: iter/trait.IndexedParallelIterator.html | |
2c00a5a8 XL |
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 | //! | |
49aad941 FG |
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 | //! | |
2c00a5a8 XL |
84 | //! # Other questions? |
85 | //! | |
86 | //! See [the Rayon FAQ][faq]. | |
87 | //! | |
88 | //! [faq]: https://github.com/rayon-rs/rayon/blob/master/FAQ.md | |
89 | ||
2c00a5a8 XL |
90 | #[macro_use] |
91 | mod delegate; | |
92 | ||
93 | #[macro_use] | |
94 | mod private; | |
95 | ||
96 | mod split_producer; | |
97 | ||
17df50a5 | 98 | pub mod array; |
2c00a5a8 XL |
99 | pub mod collections; |
100 | pub mod iter; | |
101 | pub mod option; | |
102 | pub mod prelude; | |
103 | pub mod range; | |
416331ca | 104 | pub mod range_inclusive; |
2c00a5a8 XL |
105 | pub mod result; |
106 | pub mod slice; | |
107 | pub mod str; | |
5869c6ff | 108 | pub mod string; |
2c00a5a8 XL |
109 | pub mod vec; |
110 | ||
2c00a5a8 | 111 | mod math; |
416331ca | 112 | mod par_either; |
2c00a5a8 | 113 | |
416331ca XL |
114 | mod compile_fail; |
115 | ||
116 | pub use rayon_core::FnContext; | |
117 | pub use rayon_core::ThreadBuilder; | |
2c00a5a8 | 118 | pub use rayon_core::ThreadPool; |
2c00a5a8 | 119 | pub use rayon_core::ThreadPoolBuildError; |
416331ca | 120 | pub use rayon_core::ThreadPoolBuilder; |
487cf647 | 121 | pub use rayon_core::{broadcast, spawn_broadcast, BroadcastContext}; |
04454e1e | 122 | pub use rayon_core::{current_num_threads, current_thread_index, max_num_threads}; |
17df50a5 XL |
123 | pub use rayon_core::{in_place_scope, scope, Scope}; |
124 | pub use rayon_core::{in_place_scope_fifo, scope_fifo, ScopeFifo}; | |
2c00a5a8 | 125 | pub use rayon_core::{join, join_context}; |
416331ca | 126 | pub use rayon_core::{spawn, spawn_fifo}; |
49aad941 | 127 | pub use rayon_core::{yield_local, yield_now, Yield}; |
04454e1e FG |
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 | ||
487cf647 FG |
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 | ||
04454e1e FG |
152 | // Implement Clone without the T: Clone bound from the derive |
153 | impl<T> Clone for SendPtr<T> { | |
154 | fn clone(&self) -> Self { | |
ed00b5ec | 155 | *self |
04454e1e FG |
156 | } |
157 | } | |
158 | ||
159 | // Implement Copy without the T: Copy bound from the derive | |
160 | impl<T> Copy for SendPtr<T> {} |