squawk_thread/
lib.rs

1//! A utility module for working with threads that automatically joins threads upon drop
2//! and abstracts over operating system quality of service (`QoS`) APIs
3//! through the concept of a "thread intent".
4//!
5//! The intent of a thread is frozen at thread creation time,
6//! i.e. there is no API to change the intent of a thread once it has been spawned.
7//!
8//! As a system, rust-analyzer should have the property that
9//! old manual scheduling APIs are replaced entirely by `QoS`.
10//! To maintain this invariant, we panic when it is clear that
11//! old scheduling APIs have been used.
12//!
13//! Moreover, we also want to ensure that every thread has an intent set explicitly
14//! to force a decision about its importance to the system.
15//! Thus, [`ThreadIntent`] has no default value
16//! and every entry point to creating a thread requires a [`ThreadIntent`] upfront.
17
18use std::fmt;
19
20pub use crate::intent::ThreadIntent;
21pub use crate::pool::Pool;
22
23mod intent;
24mod pool;
25
26/// # Panics
27///
28/// Panics if failed to spawn the thread.
29pub fn spawn<F, T>(intent: ThreadIntent, name: String, f: F) -> JoinHandle<T>
30where
31    F: (FnOnce() -> T) + Send + 'static,
32    T: Send + 'static,
33{
34    Builder::new(intent, name)
35        .spawn(f)
36        .expect("failed to spawn thread")
37}
38
39pub struct Builder {
40    intent: ThreadIntent,
41    inner: jod_thread::Builder,
42    allow_leak: bool,
43}
44
45impl Builder {
46    #[must_use]
47    pub fn new(intent: ThreadIntent, name: impl Into<String>) -> Self {
48        Self {
49            intent,
50            inner: jod_thread::Builder::new().name(name.into()),
51            allow_leak: false,
52        }
53    }
54
55    #[must_use]
56    pub fn stack_size(self, size: usize) -> Self {
57        Self {
58            inner: self.inner.stack_size(size),
59            ..self
60        }
61    }
62
63    /// Whether dropping should detach the thread
64    /// instead of joining it.
65    #[must_use]
66    pub fn allow_leak(self, allow_leak: bool) -> Self {
67        Self { allow_leak, ..self }
68    }
69
70    pub fn spawn<F, T>(self, f: F) -> std::io::Result<JoinHandle<T>>
71    where
72        F: (FnOnce() -> T) + Send + 'static,
73        T: Send + 'static,
74    {
75        let inner_handle = self.inner.spawn(move || {
76            self.intent.apply_to_current_thread();
77            f()
78        })?;
79
80        Ok(JoinHandle {
81            inner: Some(inner_handle),
82            allow_leak: self.allow_leak,
83        })
84    }
85}
86
87pub struct JoinHandle<T = ()> {
88    // `inner` is an `Option` so that we can
89    // take ownership of the contained `JoinHandle`.
90    inner: Option<jod_thread::JoinHandle<T>>,
91    allow_leak: bool,
92}
93
94impl<T> JoinHandle<T> {
95    /// # Panics
96    ///
97    /// Panics if there is no thread to join.
98    #[must_use]
99    pub fn join(mut self) -> T {
100        self.inner.take().unwrap().join()
101    }
102}
103
104impl<T> Drop for JoinHandle<T> {
105    fn drop(&mut self) {
106        if !self.allow_leak {
107            return;
108        }
109
110        if let Some(join_handle) = self.inner.take() {
111            join_handle.detach();
112        }
113    }
114}
115
116impl<T> fmt::Debug for JoinHandle<T> {
117    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
118        f.pad("JoinHandle { .. }")
119    }
120}
squawk_thread/lib.rs

squawk_thread/
lib.rs
