1use 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
56pub const LOCK_PATIENCE: Duration = Duration::from_secs(30);
60
61const LOCK_SPINS: u32 = 64;
64
65const LOCK_POLL: Duration = Duration::from_millis(1);
68
69#[derive(Debug, Clone, PartialEq, Eq)]
71pub struct LockError {
72 what: &'static str,
74 waited: Duration,
76}
77
78impl LockError {
79 #[must_use]
81 pub const fn what(&self) -> &'static str {
82 self.what
83 }
84
85 #[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
110pub 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
124pub 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
156pub 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#[derive(Debug)]
174pub struct StartError {
175 what: String,
177 attempts: u32,
179 waited: Duration,
181 error: io::Error,
183}
184
185impl StartError {
186 #[must_use]
188 pub fn what(&self) -> &str {
189 &self.what
190 }
191
192 #[must_use]
194 pub const fn attempts(&self) -> u32 {
195 self.attempts
196 }
197
198 #[must_use]
200 pub const fn waited(&self) -> Duration {
201 self.waited
202 }
203
204 #[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
234impl std::error::Error for StartError {}
237
238#[derive(Debug)]
240pub struct JoinHandle<T>(thread::JoinHandle<Option<T>>);
241
242impl<T> JoinHandle<T> {
243 pub fn join(self) -> thread::Result<T> {
251 self.0.join().and_then(ran)
252 }
253
254 #[must_use]
256 pub fn thread(&self) -> &Thread {
257 self.0.thread()
258 }
259}
260
261#[derive(Debug)]
263pub struct ScopedJoinHandle<'scope, T>(thread::ScopedJoinHandle<'scope, Option<T>>);
264
265impl<T> ScopedJoinHandle<'_, T> {
266 pub fn join(self) -> thread::Result<T> {
274 self.0.join().and_then(ran)
275 }
276
277 #[must_use]
279 pub fn thread(&self) -> &Thread {
280 self.0.thread()
281 }
282}
283
284fn ran<T>(result: Option<T>) -> thread::Result<T> {
288 result.ok_or_else(missing_work)
289}
290
291fn missing_work() -> Box<dyn Any + Send> {
293 Box::new("the thread found no work to run")
294}
295
296struct Slot<F>(Mutex<Option<F>>);
299
300impl<F> Slot<F> {
301 const fn new(work: F) -> Self {
303 Self(Mutex::new(Some(work)))
304 }
305
306 fn take(&self) -> Option<F> {
310 lock(&self.0, "the work of a thread").ok()?.take()
311 }
312}
313
314pub 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
347pub 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
382fn 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
402fn 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#[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 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 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#[cfg(debug_assertions)]
487mod hooks {
488 pub(crate) use crate::testing::{adopt, current, next_failure, record_wait};
489}
490
491#[cfg(not(debug_assertions))]
493mod hooks {
494 use std::{io, time::Duration};
495
496 pub(crate) const fn current() {}
498
499 pub(crate) const fn adopt(_inherited: ()) {}
501
502 pub(crate) const fn next_failure(_name: &str) -> Option<(io::Error, ())> {
504 None
505 }
506
507 pub(crate) const fn record_wait(
509 _injection: &(),
510 _wait: Duration,
511 ) {
512 }
513}
514
515#[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 pub const EAGAIN: i32 = 11;
539
540 #[derive(Debug, Clone, Copy, PartialEq, Eq)]
542 pub enum Failure {
543 Busy,
545 Os(i32),
547 }
548
549 impl Failure {
550 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 #[derive(Debug)]
561 pub(crate) struct Failures {
562 remaining: u32,
564 failure: Failure,
566 name: Option<String>,
568 waits: Vec<Duration>,
571 }
572
573 pub(crate) type Shared = Arc<Mutex<Failures>>;
575
576 thread_local! {
577 static CURRENT: Cell<Option<Shared>> = const { Cell::new(None) };
579 }
580
581 static PROCESS: Mutex<Option<Shared>> = Mutex::new(None);
583
584 fn lock<T>(mutex: &Mutex<T>) -> Option<MutexGuard<'_, T>> {
588 super::lock(mutex, "the failures of thread starts").ok()
589 }
590
591 fn replace(failures: Option<Shared>) -> Option<Shared> {
593 CURRENT
594 .try_with(|cell| cell.replace(failures))
595 .ok()
596 .flatten()
597 }
598
599 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 pub(crate) fn adopt(failures: Option<Shared>) {
613 drop(replace(failures));
614 }
615
616 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 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 #[derive(Debug)]
646 #[must_use = "the failures end when this is dropped"]
647 pub struct Injected {
648 shared: Shared,
650 previous: Option<Shared>,
652 }
653
654 impl Injected {
655 #[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 #[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 pub fn fail_starts(
677 count: u32,
678 failure: Failure,
679 ) -> Injected {
680 inject(count, failure, None)
681 }
682
683 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 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 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#[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 #[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 #[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 #[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 const AT_ONCE: Duration = Duration::from_secs(5);
805
806 #[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 #[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 #[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 #[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 #[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 #[test]
937 fn failures_reach_only_their_thread_and_its_helper_threads() {
938 let failures = fail_starts(1, Failure::Busy);
939 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 let inner = spawn("kizz-test", "the outer thread", || {
950 spawn("kizz-test", "the inner thread", || 3)
951 .unwrap()
952 .join()
953 .unwrap()
954 });
955 assert_eq!(inner.unwrap().join().unwrap(), 3);
957 assert_eq!(failures.remaining(), 0);
958 assert_eq!(failures.waits(), [WAITS[0]]);
959 drop(failures);
960 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 #[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 #[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 #[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 #[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}