1mod budget;
17mod map;
18mod policy;
19mod pool;
20
21pub(crate) use map::pool_worthwhile;
22pub(crate) use pool::{run_ordered_batches, run_ordered_pool};
23
24pub use budget::share_worker_budget_across_processes;
25pub(crate) use budget::FilesystemWork;
26pub use map::{
27 par_map, parallel_worthwhile, try_par_map, try_par_map_force, try_par_map_with_local,
28};
29pub use policy::{ParallelOp, ParallelOptions, ThreadPolicy};
30
31use std::num::NonZeroUsize;
32
33#[derive(Debug, Clone, PartialEq, Eq)]
38#[non_exhaustive]
39pub enum ParallelHashError<E> {
40 Task(E),
42}
43
44impl<E: std::fmt::Display> std::fmt::Display for ParallelHashError<E> {
45 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
46 match self {
47 Self::Task(e) => write!(f, "{e}"),
48 }
49 }
50}
51
52impl<E: std::fmt::Debug + std::fmt::Display> std::error::Error for ParallelHashError<E> {}
53
54#[derive(Debug, Clone, Copy, PartialEq, Eq)]
59pub struct Parallelism {
60 threads: NonZeroUsize,
61}
62
63impl Parallelism {
64 #[must_use]
66 pub fn new(threads: NonZeroUsize) -> Self {
67 Self { threads }
68 }
69
70 #[must_use]
72 pub fn resolve(requested: Option<usize>) -> Self {
73 let avail = std::thread::available_parallelism()
74 .map(NonZeroUsize::get)
75 .unwrap_or(1);
76 let n = match requested {
77 None | Some(0) => avail,
78 Some(n) => n.min(avail),
79 };
80 Self {
81 threads: NonZeroUsize::new(n.max(1)).unwrap_or(NonZeroUsize::MIN),
82 }
83 }
84
85 #[must_use]
87 pub fn threads(self) -> NonZeroUsize {
88 self.threads
89 }
90}
91
92#[must_use]
94pub fn index_parallelism_from_config(config: &crate::config::ConfigSet) -> Parallelism {
95 ThreadPolicy::default()
96 .resolve(ParallelOp::IndexRefresh, config)
97 .parallelism()
98}
99
100pub fn index_pack_threads_for_ingest(
105 policy: ThreadPolicy,
106 config: &crate::config::ConfigSet,
107 explicit: Option<usize>,
108) -> Result<Option<usize>, crate::error::ConfigError> {
109 if let Some(n) = explicit {
110 return Ok(Some(n));
111 }
112 if policy.threads_override.is_some() {
113 return Ok(Some(
114 policy
115 .try_resolve(ParallelOp::IndexPack, config)?
116 .threads
117 .get(),
118 ));
119 }
120 Ok(None)
121}
122
123#[cfg(test)]
124mod tests {
125 use super::*;
126 use std::sync::atomic::{AtomicUsize, Ordering};
127 use std::sync::Arc;
128
129 fn threads(n: usize) -> NonZeroUsize {
130 NonZeroUsize::new(n).expect("non-zero threads")
131 }
132
133 #[test]
134 fn try_par_map_preserves_order() {
135 let items: Vec<usize> = (0..256).collect();
136 let opts = ParallelOptions {
137 threads: threads(4),
138 min_items: 0,
139 min_total_bytes: None,
140 signed_entry_threshold: None,
141 };
142 let got = par_map(&items, opts, items.len(), |&x| x * 2);
143 let expect: Vec<_> = items.iter().map(|x| x * 2).collect();
144 assert_eq!(got, expect);
145 }
146
147 #[test]
148 fn try_par_map_surfaces_task_error() {
149 let items: Vec<i32> = (0..128).collect();
150 let opts = ParallelOptions {
151 threads: threads(4),
152 min_items: 0,
153 min_total_bytes: None,
154 signed_entry_threshold: None,
155 };
156 let err = try_par_map(&items, opts, items.len(), |&x| {
157 if x == 64 {
158 Err("boom")
159 } else {
160 Ok(x)
161 }
162 })
163 .unwrap_err();
164 assert_eq!(err, ParallelHashError::Task("boom"));
165 }
166
167 #[test]
168 fn ordered_batches_consume_in_item_order_with_worker_state() {
169 let items: Vec<usize> = (0..1000).collect();
170 let inits = AtomicUsize::new(0);
171 let mut seen = Vec::new();
172 let mut batch_lens = Vec::new();
173 run_ordered_batches(
174 &items,
175 7,
176 4,
177 || {
178 inits.fetch_add(1, Ordering::Relaxed);
179 0usize
180 },
181 |mapped: &mut usize, &x| -> Result<usize, ()> {
182 *mapped += 1;
183 Ok(x * 3)
184 },
185 |batch, results| {
186 assert_eq!(batch.len(), results.len());
187 batch_lens.push(batch.len());
188 seen.extend(results);
189 Ok(())
190 },
191 )
192 .expect("batches");
193 assert_eq!(seen, items.iter().map(|x| x * 3).collect::<Vec<_>>());
194 assert_eq!(batch_lens.iter().sum::<usize>(), items.len());
195 assert!(batch_lens[..batch_lens.len() - 1].iter().all(|&n| n == 7));
196 assert_eq!(
197 inits.load(Ordering::Relaxed),
198 4,
199 "init runs once per worker"
200 );
201 }
202
203 #[test]
204 fn ordered_batches_surface_map_and_consume_errors() {
205 let items: Vec<i32> = (0..500).collect();
206 let err = run_ordered_batches(
207 &items,
208 10,
209 3,
210 || (),
211 |_, &x| if x == 250 { Err("map") } else { Ok(x) },
212 |_, _| Ok(()),
213 )
214 .unwrap_err();
215 assert_eq!(err, "map");
216
217 let mut consumed = 0;
218 let err = run_ordered_batches(
219 &items,
220 10,
221 3,
222 || (),
223 |_, &x| Ok::<_, &str>(x),
224 |_, _| {
225 consumed += 1;
226 if consumed == 2 {
227 Err("consume")
228 } else {
229 Ok(())
230 }
231 },
232 )
233 .unwrap_err();
234 assert_eq!(err, "consume");
235 assert_eq!(consumed, 2, "no batch is consumed after an error");
236
237 run_ordered_batches(
238 &[] as &[i32],
239 10,
240 3,
241 || (),
242 |_, &x| Ok::<_, ()>(x),
243 |_, _| panic!("nothing to consume"),
244 )
245 .expect("empty input");
246 }
247
248 #[test]
249 fn ordered_batches_resume_worker_panics() {
250 let items: Vec<i32> = (0..200).collect();
251 let outcome = std::panic::catch_unwind(|| {
252 run_ordered_batches(
253 &items,
254 5,
255 4,
256 || (),
257 |_, &x| -> Result<i32, ()> {
258 assert!(x != 120, "worker boom");
259 Ok(x)
260 },
261 |_, _| Ok(()),
262 )
263 });
264 assert!(outcome.is_err());
265 }
266
267 #[test]
268 fn index_pack_threads_for_ingest_honors_override_only() {
269 let cfg = config_from("[pack]\n\tthreads = 2\n");
270 assert_eq!(
271 index_pack_threads_for_ingest(ThreadPolicy::default(), &cfg, None).expect("ingest"),
272 None
273 );
274 assert_eq!(
275 index_pack_threads_for_ingest(ThreadPolicy::default(), &cfg, Some(3)).expect("ingest"),
276 Some(3)
277 );
278 let policy = ThreadPolicy::with_threads_override(Some(6));
279 assert_eq!(
280 index_pack_threads_for_ingest(policy, &cfg, None).expect("ingest"),
281 Some(policy.resolve(ParallelOp::IndexPack, &cfg).threads.get())
282 );
283 }
284
285 fn config_from(text: &str) -> crate::config::ConfigSet {
286 use crate::config::{ConfigFile, ConfigScope, ConfigSet};
287 use std::path::Path;
288 let file = ConfigFile::parse(Path::new("test"), text, ConfigScope::Local).expect("parse");
289 let mut set = ConfigSet::new();
290 set.merge(&file);
291 set
292 }
293
294 #[test]
295 fn try_par_map_with_local_reuses_per_worker_state() {
296 let items: Vec<i32> = (0..256).collect();
297 let opts = ParallelOptions {
298 threads: threads(4),
299 min_items: 0,
300 min_total_bytes: None,
301 signed_entry_threshold: None,
302 };
303 let init_count = Arc::new(AtomicUsize::new(0));
304 let init_count_for_init = Arc::clone(&init_count);
305 let got = try_par_map_with_local(
306 &items,
307 opts,
308 items.len(),
309 move || {
310 init_count_for_init.fetch_add(1, Ordering::SeqCst);
311 0_i32
312 },
313 |state, &x| -> Result<i32, ()> {
314 *state += 1;
315 Ok(x + *state)
316 },
317 )
318 .expect("map");
319 assert_eq!(got.len(), items.len());
320 let inits = init_count.load(Ordering::SeqCst);
321 assert!(
322 inits >= 2,
323 "expected multiple workers to init state, got {inits}"
324 );
325 assert!(
326 inits <= 4,
327 "init count should not exceed worker count, got {inits}"
328 );
329 }
330}