Skip to main content

kizz_threads/
lib.rs

1// Copyright (c) 2026 Sakura Industries LLC.
2//
3// SPDX-License-Identifier: AGPL-3.0-only
4
5//! The one place where kizz starts threads, and where it locks the state that
6//! threads share ("Kizz never panics").
7//!
8//! [`spawn`] starts a named thread, and [`spawn_scoped`] starts one in a
9//! [`std::thread::scope`]. Neither panics: where `std::thread::spawn` and
10//! `std::thread::Scope::spawn` panic when the system refuses a thread, these return
11//! a [`StartError`]. When the system cannot start a thread for the moment, which it
12//! reports as `EAGAIN` and Rust as [`io::ErrorKind::WouldBlock`], they wait and try
13//! again, after each of the waits of [`WAITS`] in turn: 100, 200, 400, 800, 1,600
14//! and 3,200 milliseconds, then 4 seconds four times, 22.3 seconds in all. Any other
15//! error, or a tenth retry that fails, is the error, which names the thread, the
16//! attempts, the time waited and the system's error. The waits have no random part,
17//! and each start retries on its own, so a start never waits longer than that.
18//!
19//! `std::thread::Builder` drops the work of a start that fails, so the helper keeps
20//! the work outside each attempt, and a thread that starts after retries runs it
21//! exactly once. The helper's calls of `std::thread::Builder` sit in one private
22//! module, under the one allowance of production code for the bans of `clippy.toml`,
23//! which forbid every other way of starting a thread.
24//!
25//! In builds with `debug_assertions`, which tests use and release builds lack, the
26//! module `testing` can make the next attempts to start threads fail on purpose,
27//! for one thread and the threads that it starts through the helper, or for every
28//! thread of the process. Those attempts go through the same retries, which then
29//! record each wait instead of sleeping, so tests check the waits exactly and finish
30//! at once. A release build has no such module and cannot fail a start on purpose.
31//!
32//! [`lock`] locks a [`Mutex`] without `Mutex::lock`, which may panic when the
33//! calling thread already holds the lock. It tries the lock with
34//! `Mutex::try_lock`, which cannot panic, and while another holder keeps it,
35//! it yields and then sleeps between tries, for at most [`LOCK_PATIENCE`]; a
36//! lock that stays held that long, such as one that the calling thread holds
37//! itself, is a [`LockError`] that names what the lock guards. A lock that a
38//! panicking thread left behind is taken as it is, as `Mutex::lock` would
39//! return it with its poison.
40//!
41//! [`overflow`] holds kizz's handler of stack overflows. Once [`overflow::install`]
42//! has installed it, [`spawn`] and [`spawn_scoped`] set up each thread at the start
43//! of its work, with an alternate signal stack and the guard region of its stack,
44//! and undo that when the work ends; before then, they do nothing new.
45
46use std::{
47    any::Any,
48    fmt, io,
49    sync::{Arc, Mutex, MutexGuard, TryLockError},
50    thread::{self, Scope, Thread},
51    time::{Duration, Instant},
52};
53
54pub mod overflow;
55
56/// How long [`lock`] waits for a lock that another holder keeps before it gives
57/// up: far longer than kizz holds any lock, which is only for a few operations on
58/// the data that it guards.
59pub const LOCK_PATIENCE: Duration = Duration::from_secs(30);
60
61/// How many times [`lock_within`] yields between tries before it sleeps between
62/// them instead.
63const LOCK_SPINS: u32 = 64;
64
65/// How long [`lock_within`] sleeps between tries after it has yielded
66/// [`LOCK_SPINS`] times.
67const LOCK_POLL: Duration = Duration::from_millis(1);
68
69/// A lock that stayed held for longer than kizz waits for it.
70#[derive(Debug, Clone, PartialEq, Eq)]
71pub struct LockError {
72    /// What the lock guards, such as "the build's warnings".
73    what: &'static str,
74    /// How long the tries waited in all.
75    waited: Duration,
76}
77
78impl LockError {
79    /// What the lock guards, such as "the build's warnings".
80    #[must_use]
81    pub const fn what(&self) -> &'static str {
82        self.what
83    }
84
85    /// How long the tries waited in all.
86    #[must_use]
87    pub const fn waited(&self) -> Duration {
88        self.waited
89    }
90}
91
92impl fmt::Display for LockError {
93    fn fmt(
94        &self,
95        f: &mut fmt::Formatter<'_>,
96    ) -> fmt::Result {
97        let tenths = self.waited.as_millis().checked_div(100).unwrap_or_default();
98        write!(
99            f,
100            "could not lock {}: it stayed locked for {}.{} seconds",
101            self.what,
102            tenths.checked_div(10).unwrap_or_default(),
103            tenths.checked_rem(10).unwrap_or_default(),
104        )
105    }
106}
107
108impl std::error::Error for LockError {}
109
110/// Lock `mutex`, which guards `what`, such as "the build's warnings", waiting at
111/// most [`LOCK_PATIENCE`] while another holder keeps it.
112///
113/// # Errors
114///
115/// A [`LockError`] that names `what` when the lock stays held for
116/// [`LOCK_PATIENCE`], such as a lock that the calling thread holds itself.
117pub fn lock<'m, T: ?Sized>(
118    mutex: &'m Mutex<T>,
119    what: &'static str,
120) -> Result<MutexGuard<'m, T>, LockError> {
121    lock_within(mutex, what, LOCK_PATIENCE)
122}
123
124/// Lock `mutex`, which guards `what`, waiting at most `patience` while another
125/// holder keeps it: [`lock`] with a patience of its own, for tests.
126///
127/// # Errors
128///
129/// A [`LockError`] that names `what` when the lock stays held for `patience`.
130pub fn lock_within<'m, T: ?Sized>(
131    mutex: &'m Mutex<T>,
132    what: &'static str,
133    patience: Duration,
134) -> Result<MutexGuard<'m, T>, LockError> {
135    let started = Instant::now();
136    let mut tries: u32 = 0;
137    loop {
138        match mutex.try_lock() {
139            Ok(guard) => return Ok(guard),
140            Err(TryLockError::Poisoned(poisoned)) => return Ok(poisoned.into_inner()),
141            Err(TryLockError::WouldBlock) => {},
142        }
143        let waited = started.elapsed();
144        if waited >= patience {
145            return Err(LockError { what, waited });
146        }
147        if tries < LOCK_SPINS {
148            thread::yield_now();
149        } else {
150            thread::sleep(LOCK_POLL);
151        }
152        tries = tries.saturating_add(1);
153    }
154}
155
156/// The waits before each retry of a start that the system refused for the moment:
157/// they double from 100 milliseconds up to 4 seconds, 22.3 seconds in all, so a
158/// start makes at most 11 attempts.
159pub const WAITS: [Duration; 10] = [
160    Duration::from_millis(100),
161    Duration::from_millis(200),
162    Duration::from_millis(400),
163    Duration::from_millis(800),
164    Duration::from_millis(1_600),
165    Duration::from_millis(3_200),
166    Duration::from_secs(4),
167    Duration::from_secs(4),
168    Duration::from_secs(4),
169    Duration::from_secs(4),
170];
171
172/// A thread that could not be started.
173#[derive(Debug)]
174pub struct StartError {
175    /// What the thread is for, such as "the tracing thread".
176    what: String,
177    /// How many attempts were made.
178    attempts: u32,
179    /// How long the attempts waited in all.
180    waited: Duration,
181    /// The error of the last attempt.
182    error: io::Error,
183}
184
185impl StartError {
186    /// What the thread is for, such as "the tracing thread".
187    #[must_use]
188    pub fn what(&self) -> &str {
189        &self.what
190    }
191
192    /// How many attempts were made: 11 when every retry met `EAGAIN`.
193    #[must_use]
194    pub const fn attempts(&self) -> u32 {
195        self.attempts
196    }
197
198    /// How long the attempts waited in all.
199    #[must_use]
200    pub const fn waited(&self) -> Duration {
201        self.waited
202    }
203
204    /// The system's error of the last attempt.
205    #[must_use]
206    pub const fn error(&self) -> &io::Error {
207        &self.error
208    }
209}
210
211impl fmt::Display for StartError {
212    fn fmt(
213        &self,
214        f: &mut fmt::Formatter<'_>,
215    ) -> fmt::Result {
216        let tenths = self.waited.as_millis().checked_div(100).unwrap_or_default();
217        write!(
218            f,
219            "could not start {} after {} {} in {}.{} seconds: {}",
220            self.what,
221            self.attempts,
222            if self.attempts == 1 {
223                "attempt"
224            } else {
225                "attempts"
226            },
227            tenths.checked_div(10).unwrap_or_default(),
228            tenths.checked_rem(10).unwrap_or_default(),
229            self.error,
230        )
231    }
232}
233
234// The message holds the system's error, so the error has no source of its own,
235// and a chain of errors does not print it twice.
236impl std::error::Error for StartError {}
237
238/// The handle of a thread that [`spawn`] started.
239#[derive(Debug)]
240pub struct JoinHandle<T>(thread::JoinHandle<Option<T>>);
241
242impl<T> JoinHandle<T> {
243    /// Wait for the thread to finish and return its result, or the payload of its
244    /// panic.
245    ///
246    /// # Errors
247    ///
248    /// The payload of the thread's panic, as [`std::thread::JoinHandle::join`]
249    /// returns it.
250    pub fn join(self) -> thread::Result<T> {
251        self.0.join().and_then(ran)
252    }
253
254    /// The thread.
255    #[must_use]
256    pub fn thread(&self) -> &Thread {
257        self.0.thread()
258    }
259}
260
261/// The handle of a thread that [`spawn_scoped`] started.
262#[derive(Debug)]
263pub struct ScopedJoinHandle<'scope, T>(thread::ScopedJoinHandle<'scope, Option<T>>);
264
265impl<T> ScopedJoinHandle<'_, T> {
266    /// Wait for the thread to finish and return its result, or the payload of its
267    /// panic.
268    ///
269    /// # Errors
270    ///
271    /// The payload of the thread's panic, as
272    /// [`std::thread::ScopedJoinHandle::join`] returns it.
273    pub fn join(self) -> thread::Result<T> {
274        self.0.join().and_then(ran)
275    }
276
277    /// The thread.
278    #[must_use]
279    pub fn thread(&self) -> &Thread {
280        self.0.thread()
281    }
282}
283
284/// The result of a thread's work, or, as the payload of a panic, the message that
285/// says that the thread found no work. Neither function that starts a thread gives
286/// a thread that runs without its work, so the payload is never seen.
287fn ran<T>(result: Option<T>) -> thread::Result<T> {
288    result.ok_or_else(missing_work)
289}
290
291/// The payload that [`ran`] gives a thread that found no work.
292fn missing_work() -> Box<dyn Any + Send> {
293    Box::new("the thread found no work to run")
294}
295
296/// The work of a start, kept outside each attempt so that an attempt that fails
297/// drops only its own reference to it.
298struct Slot<F>(Mutex<Option<F>>);
299
300impl<F> Slot<F> {
301    /// A slot that holds `work`.
302    const fn new(work: F) -> Self {
303        Self(Mutex::new(Some(work)))
304    }
305
306    /// The work, the first time it is taken. Only the thread that started takes
307    /// it, so its lock is never held by another; a lock that stayed held would
308    /// give no work, which [`ran`] turns into an error of the thread.
309    fn take(&self) -> Option<F> {
310        lock(&self.0, "the work of a thread").ok()?.take()
311    }
312}
313
314/// Start a thread named `name`, which is `what`, such as "the tracing thread", to
315/// run `work`, retrying while the system cannot start it for the moment.
316///
317/// # Errors
318///
319/// A [`StartError`] when the system refuses the thread with an error other than
320/// `EAGAIN`, at once, or when its tenth retry fails with `EAGAIN`, after every wait
321/// of [`WAITS`]. A `name` that holds a NUL byte is refused without an attempt. The
322/// work never runs then.
323pub fn spawn<F, T>(
324    name: &str,
325    what: &str,
326    work: F,
327) -> Result<JoinHandle<T>, StartError>
328where
329    F: FnOnce() -> T + Send + 'static,
330    T: Send + 'static,
331{
332    check_name(name, what)?;
333    let slot = Arc::new(Slot::new(work));
334    let inherited = hooks::current();
335    retry(name, what, || {
336        let slot = Arc::clone(&slot);
337        let inherited = inherited.clone();
338        os::spawn(name, move || {
339            hooks::adopt(inherited);
340            let _overflow = overflow::guard_thread();
341            slot.take().map(|work| work())
342        })
343    })
344    .map(JoinHandle)
345}
346
347/// Start a thread named `name` in `scope`, which is `what`, such as "the thread that
348/// feeds stdin", to run `work`, retrying while the system cannot start it for the
349/// moment.
350///
351/// # Errors
352///
353/// A [`StartError`] when the system refuses the thread with an error other than
354/// `EAGAIN`, at once, or when its tenth retry fails with `EAGAIN`, after every wait
355/// of [`WAITS`]. A `name` that holds a NUL byte is refused without an attempt. The
356/// work never runs then.
357pub fn spawn_scoped<'scope, F, T>(
358    scope: &'scope Scope<'scope, '_>,
359    name: &str,
360    what: &str,
361    work: F,
362) -> Result<ScopedJoinHandle<'scope, T>, StartError>
363where
364    F: FnOnce() -> T + Send + 'scope,
365    T: Send + 'scope,
366{
367    check_name(name, what)?;
368    let slot = Arc::new(Slot::new(work));
369    let inherited = hooks::current();
370    retry(name, what, || {
371        let slot = Arc::clone(&slot);
372        let inherited = inherited.clone();
373        os::spawn_scoped(scope, name, move || {
374            hooks::adopt(inherited);
375            let _overflow = overflow::guard_thread();
376            slot.take().map(|work| work())
377        })
378    })
379    .map(ScopedJoinHandle)
380}
381
382/// Refuse a thread name that holds a NUL byte, which `std::thread::Builder` would
383/// panic on.
384fn check_name(
385    name: &str,
386    what: &str,
387) -> Result<(), StartError> {
388    if name.contains('\0') {
389        return Err(StartError {
390            what: what.to_owned(),
391            attempts: 0,
392            waited: Duration::ZERO,
393            error: io::Error::new(
394                io::ErrorKind::InvalidInput,
395                "the name of the thread holds a NUL byte",
396            ),
397        });
398    }
399    Ok(())
400}
401
402/// Make attempts to start the thread named `name`, which is `what`, with `attempt`,
403/// waiting after each one that fails with `EAGAIN` as [`WAITS`] says, until one
404/// succeeds, one fails with another error, or the tenth retry fails.
405fn retry<H>(
406    name: &str,
407    what: &str,
408    mut attempt: impl FnMut() -> io::Result<H>,
409) -> Result<H, StartError> {
410    let mut waits = WAITS.iter().copied();
411    let mut attempts: u32 = 0;
412    let mut waited = Duration::ZERO;
413    loop {
414        attempts = attempts.saturating_add(1);
415        let (result, injected) = match hooks::next_failure(name) {
416            Some((error, injection)) => (Err(error), Some(injection)),
417            None => (attempt(), None),
418        };
419        let error = match result {
420            Ok(handle) => return Ok(handle),
421            Err(error) => error,
422        };
423        let wait = if error.kind() == io::ErrorKind::WouldBlock {
424            waits.next()
425        } else {
426            None
427        };
428        let Some(wait) = wait else {
429            return Err(StartError {
430                what: what.to_owned(),
431                attempts,
432                waited,
433                error,
434            });
435        };
436        match injected {
437            Some(injection) => hooks::record_wait(&injection, wait),
438            None => thread::sleep(wait),
439        }
440        waited = waited.saturating_add(wait);
441    }
442}
443
444/// The only calls of `std::thread::Builder` in kizz's production code.
445#[expect(
446    clippy::disallowed_methods,
447    reason = "the helper is the one place that starts threads: it retries what \
448              std::thread::Builder refuses, where the banned calls would panic"
449)]
450mod os {
451    use std::{
452        io,
453        thread::{Builder, JoinHandle, Scope, ScopedJoinHandle},
454    };
455
456    /// Make one attempt to start a thread named `name` that runs `work`.
457    pub(super) fn spawn<F, T>(
458        name: &str,
459        work: F,
460    ) -> io::Result<JoinHandle<T>>
461    where
462        F: FnOnce() -> T + Send + 'static,
463        T: Send + 'static,
464    {
465        Builder::new().name(name.to_owned()).spawn(work)
466    }
467
468    /// Make one attempt to start a thread named `name` in `scope` that runs `work`.
469    pub(super) fn spawn_scoped<'scope, F, T>(
470        scope: &'scope Scope<'scope, '_>,
471        name: &str,
472        work: F,
473    ) -> io::Result<ScopedJoinHandle<'scope, T>>
474    where
475        F: FnOnce() -> T + Send + 'scope,
476        T: Send + 'scope,
477    {
478        Builder::new()
479            .name(name.to_owned())
480            .spawn_scoped(scope, work)
481    }
482}
483
484/// How the retries reach the failures of [`testing`], in builds with
485/// `debug_assertions`.
486#[cfg(debug_assertions)]
487mod hooks {
488    pub(crate) use crate::testing::{adopt, current, next_failure, record_wait};
489}
490
491/// The hooks of release builds, which inject nothing.
492#[cfg(not(debug_assertions))]
493mod hooks {
494    use std::{io, time::Duration};
495
496    /// What a thread passes to the threads it starts: nothing.
497    pub(crate) const fn current() {}
498
499    /// Take on what the starting thread passed: nothing.
500    pub(crate) const fn adopt(_inherited: ()) {}
501
502    /// No attempt fails on purpose.
503    pub(crate) const fn next_failure(_name: &str) -> Option<(io::Error, ())> {
504        None
505    }
506
507    /// Never called, because no attempt fails on purpose.
508    pub(crate) const fn record_wait(
509        _injection: &(),
510        _wait: Duration,
511    ) {
512    }
513}
514
515/// Failures of thread starts that tests cause on purpose, only in builds with
516/// `debug_assertions`, which tests use and release builds lack.
517///
518/// [`fail_starts`](testing::fail_starts) and
519/// [`fail_starts_named`](testing::fail_starts_named) make the next attempts of the
520/// calling thread fail, and of the threads that it starts through the helper, which
521/// share the same count; threads that it starts otherwise, and every other thread,
522/// never meet them, so tests that run at once in one process never meet each other's
523/// failures. [`fail_starts_in_process`](testing::fail_starts_in_process) makes the
524/// next attempts of every thread of the process fail, for the `kizz` binary's
525/// end-to-end test. An attempt that fails on purpose goes through the retries, which
526/// record its wait in the failures instead of sleeping.
527#[cfg(debug_assertions)]
528pub mod testing {
529    use std::{
530        cell::Cell,
531        io,
532        sync::{Arc, Mutex, MutexGuard},
533        time::Duration,
534    };
535
536    /// The error number of `EAGAIN` on Linux: the system cannot start a thread for
537    /// the moment.
538    pub const EAGAIN: i32 = 11;
539
540    /// How an attempt that fails on purpose fails.
541    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
542    pub enum Failure {
543        /// With `EAGAIN`, which the helper retries.
544        Busy,
545        /// With the system error of this number.
546        Os(i32),
547    }
548
549    impl Failure {
550        /// The error of an attempt that fails this way.
551        fn error(self) -> io::Error {
552            io::Error::from_raw_os_error(match self {
553                Self::Busy => EAGAIN,
554                Self::Os(number) => number,
555            })
556        }
557    }
558
559    /// The failures of one injection, and the waits of the attempts that met them.
560    #[derive(Debug)]
561    pub(crate) struct Failures {
562        /// How many attempts still fail.
563        remaining: u32,
564        /// How they fail.
565        failure: Failure,
566        /// The one thread name whose attempts fail, or `None` for every name.
567        name: Option<String>,
568        /// The wait after each attempt that failed with `EAGAIN` and was retried, in
569        /// order.
570        waits: Vec<Duration>,
571    }
572
573    /// Failures shared by the threads that meet them.
574    pub(crate) type Shared = Arc<Mutex<Failures>>;
575
576    thread_local! {
577        /// The failures of the calling thread, if any.
578        static CURRENT: Cell<Option<Shared>> = const { Cell::new(None) };
579    }
580
581    /// The failures of every thread of the process, if any.
582    static PROCESS: Mutex<Option<Shared>> = Mutex::new(None);
583
584    /// Lock `mutex` with [`super::lock`], whether or not a thread panicked while
585    /// holding it, or `None` when it stays held: then no attempt fails on purpose,
586    /// no wait is recorded, and the counts read as empty.
587    fn lock<T>(mutex: &Mutex<T>) -> Option<MutexGuard<'_, T>> {
588        super::lock(mutex, "the failures of thread starts").ok()
589    }
590
591    /// Put `failures` in place for the calling thread, and return those it had.
592    fn replace(failures: Option<Shared>) -> Option<Shared> {
593        CURRENT
594            .try_with(|cell| cell.replace(failures))
595            .ok()
596            .flatten()
597    }
598
599    /// The failures of the calling thread, which a thread that it starts takes on.
600    pub(crate) fn current() -> Option<Shared> {
601        CURRENT
602            .try_with(|cell| {
603                let failures = cell.take();
604                cell.set(failures.clone());
605                failures
606            })
607            .ok()
608            .flatten()
609    }
610
611    /// Take on `failures` in a new thread, as the thread that started it had them.
612    pub(crate) fn adopt(failures: Option<Shared>) {
613        drop(replace(failures));
614    }
615
616    /// The error of the next attempt to start a thread named `name`, when it fails on
617    /// purpose, with the failures that it met.
618    pub(crate) fn next_failure(name: &str) -> Option<(io::Error, Shared)> {
619        let shared = current().or_else(|| lock(&PROCESS)?.clone())?;
620        let failure = {
621            let mut failures = lock(&shared)?;
622            let applies = failures.name.as_deref().is_none_or(|only| only == name);
623            if !applies || failures.remaining == 0 {
624                return None;
625            }
626            failures.remaining = failures.remaining.saturating_sub(1);
627            failures.failure
628        };
629        Some((failure.error(), shared))
630    }
631
632    /// Record `wait` in `failures`, in place of sleeping.
633    pub(crate) fn record_wait(
634        failures: &Shared,
635        wait: Duration,
636    ) {
637        if let Some(mut failures) = lock(failures) {
638            failures.waits.push(wait);
639        }
640    }
641
642    /// Failures that the calling thread, and the threads that it starts through the
643    /// helper, meet until this is dropped; then the thread has the failures it had
644    /// before.
645    #[derive(Debug)]
646    #[must_use = "the failures end when this is dropped"]
647    pub struct Injected {
648        /// The failures.
649        shared: Shared,
650        /// The failures that the calling thread had before.
651        previous: Option<Shared>,
652    }
653
654    impl Injected {
655        /// The wait after each attempt that failed on purpose with `EAGAIN` and was
656        /// retried, in order.
657        #[must_use]
658        pub fn waits(&self) -> Vec<Duration> {
659            lock(&self.shared).map_or_else(Vec::new, |failures| failures.waits.clone())
660        }
661
662        /// How many attempts still fail.
663        #[must_use]
664        pub fn remaining(&self) -> u32 {
665            lock(&self.shared).map_or(0, |failures| failures.remaining)
666        }
667    }
668
669    impl Drop for Injected {
670        fn drop(&mut self) {
671            adopt(self.previous.take());
672        }
673    }
674
675    /// Make the next `count` attempts to start a thread fail as `failure` says.
676    pub fn fail_starts(
677        count: u32,
678        failure: Failure,
679    ) -> Injected {
680        inject(count, failure, None)
681    }
682
683    /// Make the next `count` attempts to start a thread named `name` fail as
684    /// `failure` says, and leave the starts of threads of other names alone.
685    pub fn fail_starts_named(
686        count: u32,
687        failure: Failure,
688        name: &str,
689    ) -> Injected {
690        inject(count, failure, Some(name.to_owned()))
691    }
692
693    /// Put failures in place for the calling thread.
694    fn inject(
695        count: u32,
696        failure: Failure,
697        name: Option<String>,
698    ) -> Injected {
699        let shared = Arc::new(Mutex::new(Failures {
700            remaining: count,
701            failure,
702            name,
703            waits: Vec::new(),
704        }));
705        let previous = replace(Some(Arc::clone(&shared)));
706        Injected { shared, previous }
707    }
708
709    /// Make the next `count` attempts to start any thread of the process fail with
710    /// `EAGAIN`, where the starting thread has no failures of its own.
711    pub fn fail_starts_in_process(count: u32) {
712        if let Some(mut process) = lock(&PROCESS) {
713            *process = Some(Arc::new(Mutex::new(Failures {
714                remaining: count,
715                failure: Failure::Busy,
716                name: None,
717                waits: Vec::new(),
718            })));
719        }
720    }
721}
722
723/// Unit tests of the retries, with the failures of [`testing`], and of the locks.
724#[cfg(test)]
725#[allow(
726    clippy::disallowed_methods,
727    clippy::disallowed_macros,
728    reason = "test code: a plain std thread shows that failures stay with their thread, \
729              and the tests assert"
730)]
731mod tests {
732    use std::{
733        panic,
734        sync::{
735            Arc, Mutex,
736            atomic::{AtomicUsize, Ordering},
737        },
738        thread,
739        time::{Duration, Instant},
740    };
741
742    use super::{
743        LOCK_PATIENCE, WAITS, lock, lock_within, spawn, spawn_scoped,
744        testing::{Failure, fail_starts, fail_starts_named},
745    };
746
747    /// A lock that the calling thread already holds is an error that names what
748    /// it guards and how long the tries waited, where `Mutex::lock` may panic; once
749    /// the holder lets it go, it locks again.
750    #[test]
751    fn a_lock_that_stays_held_is_an_error() {
752        let value = Mutex::new(5);
753        let held = lock(&value, "the test value").unwrap();
754        let error = lock_within(&value, "the test value", Duration::from_millis(30)).unwrap_err();
755        assert_eq!(error.what(), "the test value");
756        assert!(error.waited() >= Duration::from_millis(30), "{error:?}");
757        assert!(error.waited() < LOCK_PATIENCE, "{error:?}");
758        let message = error.to_string();
759        assert!(
760            message.starts_with("could not lock the test value: it stayed locked for 0."),
761            "{message}"
762        );
763        assert!(message.ends_with(" seconds"), "{message}");
764        drop(held);
765        assert_eq!(*lock(&value, "the test value").unwrap(), 5);
766    }
767
768    /// A lock that another thread holds for a moment is taken once it lets go.
769    #[test]
770    fn a_lock_that_another_thread_holds_is_taken_when_it_lets_go() {
771        let value = Mutex::new(0_u32);
772        thread::scope(|scope| {
773            let held = lock(&value, "the test value").unwrap();
774            let waiter = scope.spawn(|| {
775                let mut taken = lock(&value, "the test value").unwrap();
776                *taken = taken.saturating_add(1);
777            });
778            thread::sleep(Duration::from_millis(20));
779            drop(held);
780            waiter.join().unwrap();
781        });
782        assert_eq!(*lock(&value, "the test value").unwrap(), 1);
783    }
784
785    /// A lock that a panicking thread left behind is taken as it is. The thread
786    /// unwinds with `resume_unwind`, which poisons the lock without a panic message.
787    #[test]
788    fn a_poisoned_lock_is_taken_as_it_is() {
789        let value = Mutex::new(7);
790        let unwound = thread::scope(|scope| {
791            scope
792                .spawn(|| {
793                    let _held = lock(&value, "the test value").unwrap();
794                    panic::resume_unwind(Box::new("the holder unwinds"));
795                })
796                .join()
797        });
798        assert!(unwound.is_err());
799        assert!(value.is_poisoned());
800        assert_eq!(*lock(&value, "the test value").unwrap(), 7);
801    }
802
803    /// How long a test that records its waits may take: far less than the waits.
804    const AT_ONCE: Duration = Duration::from_secs(5);
805
806    /// A plain start that meets `EAGAIN` 1, 5 or 10 times starts at the next attempt,
807    /// runs its work exactly once, and records exactly the first 1, 5 or 10 waits.
808    #[test]
809    fn a_plain_start_retries_after_each_wait() {
810        for count in [1_usize, 5, 10] {
811            let started = Instant::now();
812            let failures = fail_starts(u32::try_from(count).unwrap(), Failure::Busy);
813            let runs = Arc::new(AtomicUsize::new(0));
814            let counter = Arc::clone(&runs);
815            let handle = spawn("kizz-test", "the test thread", move || {
816                counter.fetch_add(1, Ordering::SeqCst);
817                7
818            })
819            .unwrap();
820            assert_eq!(handle.join().unwrap(), 7);
821            assert_eq!(runs.load(Ordering::SeqCst), 1);
822            assert_eq!(failures.waits(), WAITS[..count]);
823            assert_eq!(failures.remaining(), 0);
824            assert!(started.elapsed() < AT_ONCE);
825        }
826    }
827
828    /// A scoped start that meets `EAGAIN` 1, 5 or 10 times starts at the next
829    /// attempt, runs its work exactly once, and records exactly the first 1, 5 or 10
830    /// waits.
831    #[test]
832    fn a_scoped_start_retries_after_each_wait() {
833        for count in [1_usize, 5, 10] {
834            let started = Instant::now();
835            let failures = fail_starts(u32::try_from(count).unwrap(), Failure::Busy);
836            let runs = AtomicUsize::new(0);
837            let value = thread::scope(|scope| {
838                spawn_scoped(scope, "kizz-test", "the test thread", || {
839                    runs.fetch_add(1, Ordering::SeqCst);
840                    11
841                })
842                .unwrap()
843                .join()
844                .unwrap()
845            });
846            assert_eq!(value, 11);
847            assert_eq!(runs.load(Ordering::SeqCst), 1);
848            assert_eq!(failures.waits(), WAITS[..count]);
849            assert!(started.elapsed() < AT_ONCE);
850        }
851    }
852
853    /// A plain start that meets `EAGAIN` 11 times fails after the 10 waits, 22.3
854    /// seconds in all, with an error that names the thread, the attempts and error 11,
855    /// and its work never runs.
856    #[test]
857    fn a_plain_start_fails_after_its_tenth_retry() {
858        let started = Instant::now();
859        let failures = fail_starts(11, Failure::Busy);
860        let runs = Arc::new(AtomicUsize::new(0));
861        let counter = Arc::clone(&runs);
862        let error = spawn("kizz-test", "the test thread", move || {
863            counter.fetch_add(1, Ordering::SeqCst);
864        })
865        .unwrap_err();
866        assert_eq!(error.attempts(), 11);
867        assert_eq!(error.waited(), Duration::from_millis(22_300));
868        assert_eq!(error.error().raw_os_error(), Some(11));
869        assert_eq!(error.what(), "the test thread");
870        let message = error.to_string();
871        assert!(
872            message
873                .starts_with("could not start the test thread after 11 attempts in 22.3 seconds: "),
874            "{message}"
875        );
876        assert!(message.ends_with("(os error 11)"), "{message}");
877        assert_eq!(failures.waits(), WAITS);
878        assert_eq!(runs.load(Ordering::SeqCst), 0);
879        assert!(started.elapsed() < AT_ONCE);
880    }
881
882    /// A scoped start that meets `EAGAIN` 11 times fails after the 10 waits, with an
883    /// error that names the thread, the attempts and error 11, and its work never
884    /// runs.
885    #[test]
886    fn a_scoped_start_fails_after_its_tenth_retry() {
887        let failures = fail_starts(11, Failure::Busy);
888        let runs = AtomicUsize::new(0);
889        let message = thread::scope(|scope| {
890            spawn_scoped(scope, "kizz-test", "the scoped test thread", || {
891                runs.fetch_add(1, Ordering::SeqCst);
892            })
893            .map(|_| ())
894            .unwrap_err()
895            .to_string()
896        });
897        assert!(
898            message.starts_with(
899                "could not start the scoped test thread after 11 attempts in 22.3 seconds: "
900            ),
901            "{message}"
902        );
903        assert!(message.ends_with("(os error 11)"), "{message}");
904        assert_eq!(failures.waits(), WAITS);
905        assert_eq!(runs.load(Ordering::SeqCst), 0);
906    }
907
908    /// A start that fails with another error returns it at once, without a wait, for
909    /// plain and scoped starts.
910    #[test]
911    fn another_error_fails_at_once() {
912        let failures = fail_starts(2, Failure::Os(12));
913        let error = spawn("kizz-test", "the test thread", || ()).unwrap_err();
914        assert_eq!(error.attempts(), 1);
915        assert_eq!(error.waited(), Duration::ZERO);
916        assert_eq!(error.error().raw_os_error(), Some(12));
917        assert!(
918            error
919                .to_string()
920                .starts_with("could not start the test thread after 1 attempt in 0.0 seconds: "),
921            "{error}"
922        );
923        let scoped = thread::scope(|scope| {
924            spawn_scoped(scope, "kizz-test", "the test thread", || ())
925                .map(|_| ())
926                .unwrap_err()
927                .attempts()
928        });
929        assert_eq!(scoped, 1);
930        assert_eq!(failures.waits(), Vec::<Duration>::new());
931    }
932
933    /// Failures reach the thread that set them and the threads that it starts
934    /// through the helper, which share their count, and no other thread, such as one
935    /// that runs another test at the same time.
936    #[test]
937    fn failures_reach_only_their_thread_and_its_helper_threads() {
938        let failures = fail_starts(1, Failure::Busy);
939        // A thread started without the helper, like another test's, never meets them.
940        let other = thread::spawn(|| {
941            spawn("kizz-test", "the other thread", || ())
942                .map(|handle| handle.join().is_ok())
943                .unwrap()
944        });
945        assert!(other.join().unwrap());
946        assert_eq!(failures.remaining(), 1);
947        // A thread that this one starts through the helper meets them in its own
948        // starts.
949        let inner = spawn("kizz-test", "the outer thread", || {
950            spawn("kizz-test", "the inner thread", || 3)
951                .unwrap()
952                .join()
953                .unwrap()
954        });
955        // The outer start met the one failure, so the inner one met none.
956        assert_eq!(inner.unwrap().join().unwrap(), 3);
957        assert_eq!(failures.remaining(), 0);
958        assert_eq!(failures.waits(), [WAITS[0]]);
959        drop(failures);
960        // A thread started through the helper takes on the failures of the thread
961        // that started it: only the inner thread is named so that it meets them.
962        let failures = fail_starts_named(2, Failure::Busy, "kizz-inner");
963        let nested = spawn("kizz-outer", "the outer thread", || {
964            spawn("kizz-inner", "the inner thread", || 5)
965                .map(|handle| handle.join().unwrap_or_default())
966        })
967        .unwrap()
968        .join()
969        .unwrap()
970        .unwrap();
971        assert_eq!(nested, 5);
972        assert_eq!(failures.remaining(), 0);
973        assert_eq!(failures.waits(), WAITS[..2]);
974    }
975
976    /// Failures set for one thread name leave the starts of other names alone.
977    #[test]
978    fn failures_for_one_name_leave_other_names_alone() {
979        let failures = fail_starts_named(3, Failure::Busy, "kizz-chosen");
980        spawn("kizz-other", "another thread", || ())
981            .unwrap()
982            .join()
983            .unwrap();
984        assert_eq!(failures.remaining(), 3);
985        spawn("kizz-chosen", "the chosen thread", || ())
986            .unwrap()
987            .join()
988            .unwrap();
989        assert_eq!(failures.remaining(), 0);
990        assert_eq!(failures.waits(), WAITS[..3]);
991    }
992
993    /// Dropping the failures gives the thread back those it had before.
994    #[test]
995    fn dropping_failures_restores_the_earlier_ones() {
996        let outer = fail_starts(1, Failure::Busy);
997        drop(fail_starts(5, Failure::Os(12)));
998        spawn("kizz-test", "the test thread", || ())
999            .unwrap()
1000            .join()
1001            .unwrap();
1002        assert_eq!(outer.remaining(), 0);
1003        assert_eq!(outer.waits(), [WAITS[0]]);
1004    }
1005
1006    /// A name that holds a NUL byte is refused without an attempt, where
1007    /// `std::thread::Builder` would panic.
1008    #[test]
1009    fn a_name_with_a_nul_byte_is_refused() {
1010        let error = spawn("kizz\0test", "the test thread", || ()).unwrap_err();
1011        assert_eq!(error.attempts(), 0);
1012        assert_eq!(error.error().kind(), std::io::ErrorKind::InvalidInput);
1013        let scoped = thread::scope(|scope| {
1014            spawn_scoped(scope, "kizz\0test", "the test thread", || ())
1015                .map(|_| ())
1016                .unwrap_err()
1017                .attempts()
1018        });
1019        assert_eq!(scoped, 0);
1020    }
1021
1022    /// The waits of the retry rule add up to 22.3 seconds.
1023    #[test]
1024    fn the_waits_add_up_to_22_3_seconds() {
1025        assert_eq!(
1026            WAITS.iter().sum::<Duration>(),
1027            Duration::from_millis(22_300)
1028        );
1029    }
1030}