kizz_core/pool.rs
1// Copyright (c) 2026 Sakura Industries LLC.
2//
3// SPDX-License-Identifier: AGPL-3.0-only
4
5//! The worker pool of a command ("Kizz never panics").
6//!
7//! A command that has parallel work builds one [`WorkerPool`] before that work, and
8//! passes it to the code that needs it: a `rayon` pool of as many threads as
9//! [`std::thread::available_parallelism`] gives, at most [`MAX_WORKERS`], and 1 when
10//! it gives an error. Each worker starts through `kizz_threads`, which waits and
11//! retries while the system cannot start a thread for the moment, and never panics;
12//! a worker that still cannot start makes [`WorkerPool::new`] return the error, and
13//! `rayon` stops the workers that started.
14//!
15//! The cache check, the recording of observations, cache cleanup, BLAKE3's parallel
16//! hashing and the discovery walk run inside the pool, through
17//! [`WorkerPool::install`], so BLAKE3's `rayon::join` runs on it too, and `rayon`'s
18//! global pool, which panics when it cannot start a thread, never starts.
19
20use std::{io, sync::Arc, thread};
21
22use rayon::{ThreadPool, ThreadPoolBuildError, ThreadPoolBuilder};
23
24/// The most threads a worker pool has. The measurement report times the check of
25/// 10,000 cached steps at 0.73 seconds with 4 threads, 0.83 seconds with 1, and 1.53
26/// seconds with the default pool of 32 threads.
27pub const MAX_WORKERS: usize = 4;
28
29/// The pool of threads that runs a command's parallel work.
30#[derive(Debug, Clone)]
31pub struct WorkerPool {
32 /// The `rayon` pool, shared by every clone.
33 pool: Arc<ThreadPool>,
34}
35
36/// A worker pool that could not be built because a worker could not start.
37#[derive(Debug, thiserror::Error)]
38#[error("cannot start kizz's worker pool: {0}")]
39pub struct PoolError(ThreadPoolBuildError);
40
41impl WorkerPool {
42 /// A pool of as many threads as [`std::thread::available_parallelism`] gives, at
43 /// most [`MAX_WORKERS`], and 1 when it gives an error.
44 ///
45 /// # Errors
46 ///
47 /// A [`PoolError`] that names the worker and the system's error when a worker
48 /// cannot start after its retries.
49 pub fn new() -> Result<Self, PoolError> {
50 let threads =
51 thread::available_parallelism().map_or(1, |threads| threads.get().min(MAX_WORKERS));
52 Self::with_threads(threads)
53 }
54
55 /// A pool of `threads` threads, at least 1.
56 ///
57 /// # Errors
58 ///
59 /// A [`PoolError`] that names the worker and the system's error when a worker
60 /// cannot start after its retries.
61 pub fn with_threads(threads: usize) -> Result<Self, PoolError> {
62 ThreadPoolBuilder::new()
63 .num_threads(threads.max(1))
64 .thread_name(|index| format!("kizz-worker-{index}"))
65 .spawn_handler(|worker| {
66 let name = worker.name().unwrap_or("kizz-worker").to_owned();
67 kizz_threads::spawn(&name, "a worker of kizz's pool", move || worker.run())
68 .map(|_detached| ())
69 .map_err(io::Error::other)
70 })
71 .build()
72 .map(|pool| {
73 Self {
74 pool: Arc::new(pool),
75 }
76 })
77 .map_err(PoolError)
78 }
79
80 /// The number of threads of the pool.
81 #[must_use]
82 pub fn threads(&self) -> usize {
83 self.pool.current_num_threads()
84 }
85
86 /// Run `work` on the pool, so that the parallel work it starts runs on the pool,
87 /// and return its result. On a thread of the pool, `work` runs at once.
88 pub fn install<R: Send>(
89 &self,
90 work: impl FnOnce() -> R + Send,
91 ) -> R {
92 self.pool.install(work)
93 }
94}
95
96/// Unit tests of building the pool, with the failures of `kizz_threads::testing`.
97#[cfg(test)]
98#[allow(
99 clippy::disallowed_macros,
100 clippy::disallowed_methods,
101 reason = "test code: the tests assert and lock"
102)]
103mod tests {
104 use kizz_threads::testing::{Failure, fail_starts};
105 use rayon::iter::{IntoParallelIterator as _, ParallelIterator as _};
106
107 use super::*;
108
109 /// A pool whose workers cannot start, even after their retries, is an error that
110 /// names the worker and error 11.
111 #[test]
112 fn a_pool_whose_workers_cannot_start_is_an_error() {
113 let _failures = fail_starts(u32::MAX, Failure::Busy);
114 let message = WorkerPool::with_threads(2).unwrap_err().to_string();
115 assert!(
116 message.starts_with(
117 "cannot start kizz's worker pool: could not start a worker of kizz's pool after \
118 11 attempts in 22.3 seconds: "
119 ),
120 "{message}"
121 );
122 assert!(message.ends_with("(os error 11)"), "{message}");
123 }
124
125 /// A pool whose workers start after retries runs parallel work.
126 #[test]
127 fn a_pool_whose_workers_start_after_retries_runs_parallel_work() {
128 let failures = fail_starts(3, Failure::Busy);
129 let pool = WorkerPool::with_threads(2).unwrap();
130 assert_eq!(failures.remaining(), 0);
131 assert_eq!(pool.threads(), 2);
132 let sum: u64 = pool.install(|| (1..=1_000_u64).into_par_iter().sum());
133 assert_eq!(sum, 500_500);
134 }
135
136 /// The pool has at least one thread and at most [`MAX_WORKERS`].
137 #[test]
138 fn the_pool_has_one_to_four_threads() {
139 assert!((1..=MAX_WORKERS).contains(&WorkerPool::new().unwrap().threads()));
140 assert_eq!(WorkerPool::with_threads(0).unwrap().threads(), 1);
141 }
142}