1use std::num::NonZeroUsize;
4
5use crate::config::ConfigSet;
6use crate::error::{BadNumericSource, ConfigError};
7use crate::worktree_scan::PARALLEL_STAT_MIN_ENTRIES;
8
9const PAR_HASH_MIN_ITEMS: usize = 32;
11const PAR_HASH_MIN_TOTAL_BYTES: usize = 256 * 1024;
13
14use super::Parallelism;
15
16#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
18pub enum ParallelOp {
19 IndexRefresh,
21 IndexLoad,
23 Checkout,
25 IndexPack,
27 PackWrite,
29 PackDeltaSearch,
31 DiffRename,
33 DiffContent,
35}
36
37#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
39pub struct ThreadPolicy {
40 pub threads_override: Option<usize>,
42 pub min_items_override: Option<usize>,
44 pub min_total_bytes_override: Option<usize>,
46}
47
48impl ThreadPolicy {
49 #[must_use]
51 pub fn with_threads_override(threads: Option<usize>) -> Self {
52 Self {
53 threads_override: threads,
54 ..Self::default()
55 }
56 }
57
58 #[must_use]
60 pub fn with_min_items_override(min_items: Option<usize>) -> Self {
61 Self {
62 min_items_override: min_items,
63 ..Self::default()
64 }
65 }
66
67 #[must_use]
69 pub fn min_items_override(mut self, min_items: Option<usize>) -> Self {
70 self.min_items_override = min_items;
71 self
72 }
73
74 #[must_use]
76 pub fn min_total_bytes_override(mut self, min_bytes: Option<usize>) -> Self {
77 self.min_total_bytes_override = min_bytes;
78 self
79 }
80
81 #[must_use]
88 pub fn resolve(&self, op: ParallelOp, config: &ConfigSet) -> ParallelOptions {
89 self.try_resolve(op, config).unwrap_or_else(|e| match op {
90 ParallelOp::IndexPack | ParallelOp::PackWrite | ParallelOp::PackDeltaSearch => {
91 panic!("invalid pack.threads config: {e}")
92 }
93 _ => unreachable!("only pack operations return config errors"),
94 })
95 }
96
97 pub fn try_resolve(
104 &self,
105 op: ParallelOp,
106 config: &ConfigSet,
107 ) -> Result<ParallelOptions, ConfigError> {
108 let preload = config.preload_index();
109 let threads = match op {
110 ParallelOp::IndexRefresh | ParallelOp::IndexLoad => {
111 if self.threads_override.is_some() || preload {
112 resolve_index_threads(config, self.threads_override)
113 } else {
114 NonZeroUsize::MIN
115 }
116 }
117 ParallelOp::DiffRename | ParallelOp::DiffContent => {
118 if self.threads_override.is_some() || preload {
119 resolve_index_threads(config, self.threads_override)
120 } else {
121 NonZeroUsize::MIN
122 }
123 }
124 ParallelOp::IndexPack | ParallelOp::PackWrite | ParallelOp::PackDeltaSearch => {
125 resolve_pack_threads(config, self.threads_override)?
126 }
127 ParallelOp::Checkout => resolve_checkout_workers(config, self.threads_override),
128 };
129
130 let (default_min_items, default_min_bytes) = match op {
131 ParallelOp::IndexRefresh => (PAR_HASH_MIN_ITEMS, Some(PAR_HASH_MIN_TOTAL_BYTES)),
132 ParallelOp::IndexLoad => (crate::index_name_hash_lazy::LAZY_THREAD_COST * 2, None),
133 ParallelOp::Checkout => (0, None),
134 ParallelOp::IndexPack | ParallelOp::PackWrite | ParallelOp::PackDeltaSearch => {
135 (0, None)
136 }
137 ParallelOp::DiffRename | ParallelOp::DiffContent => {
138 (PAR_HASH_MIN_ITEMS, Some(PAR_HASH_MIN_TOTAL_BYTES))
139 }
140 };
141
142 let min_items = self.min_items_override.unwrap_or(default_min_items);
143 let signed_entry_threshold = match op {
144 ParallelOp::Checkout => Some(checkout_parallelism_threshold(config)),
145 _ => None,
146 };
147
148 let min_total_bytes = match self.min_total_bytes_override {
149 Some(0) => None,
150 Some(n) => Some(n),
151 None => default_min_bytes,
152 };
153
154 Ok(ParallelOptions {
155 threads,
156 min_items,
157 min_total_bytes,
158 signed_entry_threshold,
159 })
160 }
161
162 #[must_use]
164 pub fn index_stat_preload_threads(
165 &self,
166 config: &ConfigSet,
167 blob_count: usize,
168 stat_parallel_threads: Option<usize>,
169 ) -> usize {
170 if !config.preload_index() || blob_count < PARALLEL_STAT_MIN_ENTRIES {
171 return 1;
172 }
173 self.index_stat_scan_threads(config, blob_count, stat_parallel_threads)
174 }
175
176 #[must_use]
179 pub(crate) fn index_stat_scan_threads(
180 &self,
181 config: &ConfigSet,
182 blob_count: usize,
183 stat_parallel_threads: Option<usize>,
184 ) -> usize {
185 const THREAD_COST: usize = 500;
186 const MAX_PARALLEL: usize = 20;
187
188 if blob_count < PARALLEL_STAT_MIN_ENTRIES {
189 return 1;
190 }
191
192 let mut threads = blob_count / THREAD_COST;
193 if threads < 2 {
194 threads = 2;
195 }
196 threads = threads.min(MAX_PARALLEL);
197
198 let index_cap = resolve_index_threads(config, self.threads_override).get();
199 threads = threads.min(index_cap);
200
201 if let Some(requested) = stat_parallel_threads {
202 if requested <= 1 {
203 return 1;
204 }
205 threads = threads.min(requested);
206 }
207
208 threads.max(1)
209 }
210}
211
212#[derive(Debug, Clone, Copy, PartialEq, Eq)]
214pub struct ParallelOptions {
215 pub threads: NonZeroUsize,
217 pub min_items: usize,
219 pub min_total_bytes: Option<usize>,
221 pub signed_entry_threshold: Option<i64>,
223}
224
225impl ParallelOptions {
226 #[must_use]
228 pub fn parallelism(self) -> Parallelism {
229 Parallelism::new(self.threads)
230 }
231}
232
233#[derive(Debug, Clone, Copy, PartialEq, Eq)]
235enum IndexThreadsSetting {
236 UnsetAuto,
238 Auto,
239 Serial,
240 Count(usize),
241}
242
243#[must_use]
244fn index_threads_setting(config: &ConfigSet) -> IndexThreadsSetting {
245 if let Ok(Some(n)) = config.get_i64("index.threads") {
246 return match n {
247 0 => IndexThreadsSetting::Auto,
248 1 => IndexThreadsSetting::Serial,
249 n if n > 1 => IndexThreadsSetting::Count(usize::try_from(n).unwrap_or(1)),
250 _ => IndexThreadsSetting::Serial,
251 };
252 }
253 if config
254 .value("index.threads")
255 .is_some_and(|v| v.trim() == "0")
256 {
257 return IndexThreadsSetting::Auto;
258 }
259 if let Ok(Some(b)) = config.get_bool("index.threads") {
260 return if b {
261 IndexThreadsSetting::Auto
262 } else {
263 IndexThreadsSetting::Serial
264 };
265 }
266 IndexThreadsSetting::UnsetAuto
267}
268
269#[must_use]
270fn resolve_index_threads(config: &ConfigSet, override_threads: Option<usize>) -> NonZeroUsize {
271 if let Some(n) = override_threads {
272 return Parallelism::resolve(Some(n)).threads();
273 }
274 match index_threads_setting(config) {
275 IndexThreadsSetting::UnsetAuto | IndexThreadsSetting::Auto => {
276 Parallelism::resolve(None).threads()
277 }
278 IndexThreadsSetting::Serial => NonZeroUsize::MIN,
279 IndexThreadsSetting::Count(n) => Parallelism::resolve(Some(n)).threads(),
280 }
281}
282
283fn parse_pack_threads(config: &ConfigSet) -> Result<Option<usize>, ConfigError> {
285 const KEY: &str = "pack.threads";
286 let Some(raw) = config.value(KEY) else {
287 return Ok(None);
288 };
289 let trimmed = raw.trim();
290 match config.get_i64(KEY) {
291 Ok(Some(n)) if n < 0 => Err(ConfigError::InvalidThreadCount {
292 key: KEY.into(),
293 value: n,
294 }),
295 Ok(Some(0)) => Ok(None),
296 Ok(Some(n)) => Ok(Some(usize::try_from(n).unwrap_or(1))),
297 Err(_) | Ok(None) => Err(ConfigError::BadNumericValue {
298 key: KEY.into(),
299 value: trimmed.into(),
300 reason: BadNumericSource::InvalidUnit,
301 }),
302 }
303}
304
305fn resolve_pack_threads(
306 config: &ConfigSet,
307 override_threads: Option<usize>,
308) -> Result<NonZeroUsize, ConfigError> {
309 if let Some(n) = override_threads {
310 return Ok(Parallelism::resolve(Some(n)).threads());
311 }
312 let requested = parse_pack_threads(config)?;
313 Ok(Parallelism::resolve(requested).threads())
314}
315
316enum CheckoutWorkersSetting {
318 Unset,
320 Auto,
322 Count(usize),
324}
325
326#[must_use]
327fn checkout_workers_setting(config: &ConfigSet) -> CheckoutWorkersSetting {
328 match config.get_i64("checkout.workers") {
329 Ok(None) | Err(_) => CheckoutWorkersSetting::Unset,
330 Ok(Some(n)) if n < 1 => CheckoutWorkersSetting::Auto,
331 Ok(Some(n)) => CheckoutWorkersSetting::Count(n as usize),
332 }
333}
334
335#[must_use]
336fn resolve_checkout_workers(config: &ConfigSet, override_threads: Option<usize>) -> NonZeroUsize {
337 let setting = checkout_workers_setting(config);
338
339 if let Some(n) = override_threads {
340 #[cfg(windows)]
341 if matches!(setting, CheckoutWorkersSetting::Unset) {
342 let _ = n;
345 return NonZeroUsize::MIN;
346 }
347 return Parallelism::resolve(Some(n)).threads();
348 }
349
350 match setting {
351 CheckoutWorkersSetting::Unset => {
352 #[cfg(windows)]
353 {
354 return NonZeroUsize::MIN;
355 }
356 #[cfg(not(windows))]
357 {
358 Parallelism::resolve(None).threads()
359 }
360 }
361 CheckoutWorkersSetting::Auto => Parallelism::resolve(None).threads(),
362 CheckoutWorkersSetting::Count(n) => Parallelism::resolve(Some(n)).threads(),
363 }
364}
365
366#[must_use]
367fn checkout_parallelism_threshold(config: &ConfigSet) -> i64 {
368 match config.get_i64("checkout.thresholdForParallelism") {
369 Ok(None) | Err(_) => 100,
370 Ok(Some(n)) => n,
371 }
372}
373
374#[cfg(test)]
375mod tests {
376 use super::*;
377 use crate::config::{ConfigScope, ConfigSet};
378 use crate::environment::Environment;
379
380 fn config_from(text: &str) -> ConfigSet {
381 use crate::config::ConfigFile;
382 use std::path::Path;
383 let file = ConfigFile::parse(Path::new("test"), text, ConfigScope::Local).expect("parse");
384 let mut set = ConfigSet::new();
385 set.merge(&file);
386 set
387 }
388
389 #[test]
390 fn index_threads_bool_and_int_semantics() {
391 let true_auto = config_from("[index]\n\tthreads = true\n");
392 assert_eq!(index_threads_setting(&true_auto), IndexThreadsSetting::Auto);
393 let false_serial = config_from("[index]\n\tthreads = false\n");
394 assert_eq!(
395 index_threads_setting(&false_serial),
396 IndexThreadsSetting::Serial
397 );
398 let zero = config_from("[index]\n\tthreads = 0\n");
399 assert_eq!(index_threads_setting(&zero), IndexThreadsSetting::Auto);
400 let one = config_from("[index]\n\tthreads = 1\n");
401 assert_eq!(index_threads_setting(&one), IndexThreadsSetting::Serial);
402 let four = config_from("[index]\n\tthreads = 4\n");
403 assert_eq!(index_threads_setting(&four), IndexThreadsSetting::Count(4));
404 let neg = config_from("[index]\n\tthreads = -3\n");
405 assert_eq!(index_threads_setting(&neg), IndexThreadsSetting::Serial);
406 }
407
408 #[test]
409 fn index_threads_negative_is_serial_for_refresh() {
410 let cfg = config_from("[index]\n\tthreads = -3\n");
411 let opts = ThreadPolicy::default().resolve(ParallelOp::IndexRefresh, &cfg);
412 assert_eq!(opts.threads, NonZeroUsize::MIN);
413 }
414
415 #[test]
416 fn pack_threads_negative_is_config_error() {
417 let cfg = config_from("[pack]\n\tthreads = -3\n");
418 let err = ThreadPolicy::default()
419 .try_resolve(ParallelOp::IndexPack, &cfg)
420 .expect_err("negative pack.threads");
421 assert_eq!(
422 err,
423 ConfigError::InvalidThreadCount {
424 key: "pack.threads".into(),
425 value: -3,
426 }
427 );
428 }
429
430 #[test]
431 fn pack_threads_bool_is_bad_numeric() {
432 for (raw, label) in [("true", "true"), ("false", "false")] {
433 let cfg = config_from(&format!("[pack]\n\tthreads = {raw}\n"));
434 let err = ThreadPolicy::default()
435 .try_resolve(ParallelOp::IndexPack, &cfg)
436 .expect_err(&format!("pack.threads = {label}"));
437 assert!(
438 matches!(
439 &err,
440 ConfigError::BadNumericValue {
441 key,
442 value,
443 reason
444 } if key == "pack.threads" && value == label && *reason == BadNumericSource::InvalidUnit
445 ),
446 "unexpected error for {label}: {err:?}"
447 );
448 }
449 }
450
451 #[test]
452 fn preload_index_disables_index_refresh_workers() {
453 let cfg = config_from("[core]\n\tpreloadIndex = false\n[index]\n\tthreads = 8\n");
454 let policy = ThreadPolicy::default();
455 let opts = policy.resolve(ParallelOp::IndexRefresh, &cfg);
456 assert_eq!(opts.threads, NonZeroUsize::MIN);
457 }
458
459 #[test]
460 fn thread_override_enables_index_refresh_when_preload_off() {
461 let cfg = config_from("[core]\n\tpreloadIndex = false\n[index]\n\tthreads = 2\n");
462 let policy = ThreadPolicy::with_threads_override(Some(6));
463 let opts = policy.resolve(ParallelOp::IndexRefresh, &cfg);
464 assert_eq!(
465 opts.threads.get(),
466 6.min(
467 std::thread::available_parallelism()
468 .map(|n| n.get())
469 .unwrap_or(1)
470 )
471 );
472 }
473
474 #[test]
475 fn thread_override_beats_config() {
476 let cfg = config_from("[index]\n\tthreads = 2\n");
477 let policy = ThreadPolicy::with_threads_override(Some(6));
478 let opts = policy.resolve(ParallelOp::IndexRefresh, &cfg);
479 assert_eq!(
480 opts.threads.get(),
481 6.min(
482 std::thread::available_parallelism()
483 .map(|n| n.get())
484 .unwrap_or(1)
485 )
486 );
487 }
488
489 #[test]
490 fn min_items_override_for_tests() {
491 let cfg = ConfigSet::new();
492 let policy = ThreadPolicy::with_min_items_override(Some(0));
493 let opts = policy.resolve(ParallelOp::IndexPack, &cfg);
494 assert_eq!(opts.min_items, 0);
495 }
496
497 #[test]
498 fn pack_threads_zero_is_auto() {
499 let cfg = config_from("[pack]\n\tthreads = 0\n");
500 let opts = ThreadPolicy::default().resolve(ParallelOp::IndexPack, &cfg);
501 assert!(opts.threads.get() > 1 || std::thread::available_parallelism().is_ok());
502 }
503
504 #[test]
505 #[cfg(not(windows))]
506 fn checkout_workers_unset_defaults_to_auto() {
507 let cfg = ConfigSet::new();
508 let opts = ThreadPolicy::default().resolve(ParallelOp::Checkout, &cfg);
509 assert_eq!(
510 opts.threads.get(),
511 std::thread::available_parallelism()
512 .map(NonZeroUsize::get)
513 .unwrap_or(1)
514 );
515 assert_eq!(opts.signed_entry_threshold, Some(100));
516 }
517
518 #[test]
519 #[cfg(windows)]
520 fn checkout_workers_unset_defaults_to_serial() {
521 let cfg = ConfigSet::new();
522 let opts = ThreadPolicy::default().resolve(ParallelOp::Checkout, &cfg);
523 assert_eq!(opts.threads, NonZeroUsize::MIN);
524 assert_eq!(opts.signed_entry_threshold, Some(100));
525 }
526
527 #[test]
528 #[cfg(windows)]
529 fn checkout_global_threads_override_ignored_without_checkout_workers() {
530 let cfg = ConfigSet::new();
531 let policy = ThreadPolicy::with_threads_override(Some(8));
532 let opts = policy.resolve(ParallelOp::Checkout, &cfg);
533 assert_eq!(opts.threads, NonZeroUsize::MIN);
534 }
535
536 #[test]
537 #[cfg(windows)]
538 fn checkout_explicit_auto_enables_parallel_workers() {
539 let cfg = config_from("[checkout]\n\tworkers = 0\n");
540 let opts = ThreadPolicy::default().resolve(ParallelOp::Checkout, &cfg);
541 assert_eq!(
542 opts.threads.get(),
543 std::thread::available_parallelism()
544 .map(NonZeroUsize::get)
545 .unwrap_or(1)
546 );
547 }
548
549 #[test]
550 #[cfg(windows)]
551 fn checkout_workers_two_respects_cpu_cap_on_windows() {
552 let cfg = config_from("[checkout]\n\tworkers = 2\n");
553 let opts = ThreadPolicy::default().resolve(ParallelOp::Checkout, &cfg);
554 assert_eq!(
555 opts.threads.get(),
556 2.min(
557 std::thread::available_parallelism()
558 .map(|n| n.get())
559 .unwrap_or(1)
560 )
561 );
562 }
563
564 #[test]
565 #[cfg(windows)]
566 fn checkout_thread_override_beats_workers_config_on_windows() {
567 let cfg = config_from("[checkout]\n\tworkers = 2\n");
568 let policy = ThreadPolicy::with_threads_override(Some(4));
569 let opts = policy.resolve(ParallelOp::Checkout, &cfg);
570 assert_eq!(
571 opts.threads.get(),
572 4.min(
573 std::thread::available_parallelism()
574 .map(|n| n.get())
575 .unwrap_or(1)
576 )
577 );
578 }
579
580 #[test]
581 fn checkout_workers_zero_is_auto() {
582 let cfg = config_from("[checkout]\n\tworkers = 0\n");
583 let opts = ThreadPolicy::default().resolve(ParallelOp::Checkout, &cfg);
584 assert_eq!(
585 opts.threads.get(),
586 std::thread::available_parallelism()
587 .map(|n| n.get())
588 .unwrap_or(1)
589 );
590 }
591
592 #[test]
593 fn checkout_threshold_negative_is_preserved() {
594 let cfg = config_from("[checkout]\n\tthresholdForParallelism = -5\n");
595 let opts = ThreadPolicy::default().resolve(ParallelOp::Checkout, &cfg);
596 assert_eq!(opts.signed_entry_threshold, Some(-5));
597 }
598
599 #[test]
600 fn checkout_threshold_negative_keeps_small_batches_serial() {
601 use crate::parallel::map::pool_worthwhile;
602 let cfg =
603 config_from("[checkout]\n\tthresholdForParallelism = -5\n[checkout]\n\tworkers = 4\n");
604 let opts = ThreadPolicy::default().resolve(ParallelOp::Checkout, &cfg);
605 assert!(!pool_worthwhile(0, 0, opts));
606 assert_eq!(pool_worthwhile(100, 0, opts), opts.threads.get() > 1);
609 }
610
611 #[test]
612 fn single_item_never_uses_the_pool() {
613 use crate::parallel::map::pool_worthwhile;
614 let opts = ParallelOptions {
615 threads: NonZeroUsize::new(8).unwrap_or(NonZeroUsize::MIN),
616 min_items: 0,
617 min_total_bytes: None,
618 signed_entry_threshold: None,
619 };
620 assert!(!pool_worthwhile(1, usize::MAX, opts));
621 assert!(pool_worthwhile(2, 0, opts));
622 }
623
624 #[test]
625 fn checkout_thread_override_beats_workers_config() {
626 let cfg = config_from("[checkout]\n\tworkers = 2\n");
627 let policy = ThreadPolicy::with_threads_override(Some(6));
628 let opts = policy.resolve(ParallelOp::Checkout, &cfg);
629 assert_eq!(
630 opts.threads.get(),
631 6.min(
632 std::thread::available_parallelism()
633 .map(|n| n.get())
634 .unwrap_or(1)
635 )
636 );
637 }
638
639 #[test]
640 fn stat_preload_respects_preload_math_and_override() {
641 let cfg = ConfigSet::new();
642 let policy = ThreadPolicy::default();
643 let index_cap = resolve_index_threads(&cfg, None).get();
644 assert_eq!(
645 policy.index_stat_preload_threads(&cfg, 5000, None),
646 10_usize.min(20).min(index_cap)
647 );
648 let policy = ThreadPolicy::with_threads_override(Some(8));
649 let override_cap = resolve_index_threads(&cfg, Some(8)).get();
650 assert_eq!(
651 policy.index_stat_preload_threads(&cfg, 5000, None),
652 10_usize.min(20).min(override_cap)
653 );
654 assert_eq!(
655 policy.index_stat_preload_threads(&cfg, 5000, Some(4)),
656 4_usize.min(override_cap)
657 );
658 }
659
660 #[test]
661 #[cfg_attr(miri, ignore = "creates a temp dir; Miri isolation blocks mkdir")]
662 fn pack_index_parallelism_for_git_dir_matches_config() {
663 let dir = tempfile::tempdir().expect("tempdir");
664 std::fs::write(dir.path().join("config"), "[pack]\n\tthreads = 3\n").expect("write config");
665 let env = Environment::empty();
666 let par = ConfigSet::pack_index_parallelism_for_git_dir(&env, Some(dir.path()));
667 assert_eq!(par.threads().get(), 3);
668 }
669}