Skip to main content

grit_lib/parallel/
mod.rs

1//! Ordered scoped-thread parallelism and Git config-driven thread policy.
2//!
3//! There is no global pool and no environment reads in this module. Embedders and
4//! the CLI pass an explicit [`ThreadPolicy`] (for example `--threads`) when opening
5//! a [`crate::repo::Repository`].
6//!
7//! Library guide: [parallelism](https://grit-scm.com/docs/library/parallelism)
8//!
9//! ```rust
10//! use grit_lib::parallel::ThreadPolicy;
11//! # fn main() {
12//! let _ = ThreadPolicy::default();
13//! # }
14//! ```
15
16mod 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/// Failure from fallible parallel helpers when a closure returns an error.
34///
35/// If a worker panics, partial results are dropped and the panic is resumed on the
36/// caller thread after workers join.
37#[derive(Debug, Clone, PartialEq, Eq)]
38#[non_exhaustive]
39pub enum ParallelHashError<E> {
40    /// The first error returned by a worker (additional concurrent errors are discarded).
41    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/// Resolved worker thread count for parallel helpers.
55///
56/// Config keys are interpreted by [`ThreadPolicy::resolve`]; this type only clamps
57/// an optional request to [`std::thread::available_parallelism`].
58#[derive(Debug, Clone, Copy, PartialEq, Eq)]
59pub struct Parallelism {
60    threads: NonZeroUsize,
61}
62
63impl Parallelism {
64    /// Use exactly `threads` workers (must be at least 1).
65    #[must_use]
66    pub fn new(threads: NonZeroUsize) -> Self {
67        Self { threads }
68    }
69
70    /// Resolve a thread count from config (`None` or `Some(0)` → all logical CPUs).
71    #[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    /// Explicit worker count passed to parallel entry points.
86    #[must_use]
87    pub fn threads(self) -> NonZeroUsize {
88        self.threads
89    }
90}
91
92/// Worker count for index preload / parallel worktree hashing from config alone.
93#[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
100/// Resolve `IngestPackOptions::threads` from explicit fetch options, CLI policy, or config.
101///
102/// Returns `Some(n)` only when `explicit` or a [`ThreadPolicy::threads_override`] is set.
103/// Otherwise returns `None` so index-pack reads `pack.threads` from the repository config.
104pub 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}