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;
22pub use crate::taskpool::TaskPool;
23
24mod intent;
25mod pool;
26mod taskpool;
27
28/// # Panics
29///
30/// Panics if failed to spawn the thread.
31pub fn spawn<F, T>(intent: ThreadIntent, name: String, f: F) -> JoinHandle<T>
32where
33    F: (FnOnce() -> T) + Send + 'static,
34    T: Send + 'static,
35{
36    Builder::new(intent, name)
37        .spawn(f)
38        .expect("failed to spawn thread")
39}
40
41pub struct Builder {
42    intent: ThreadIntent,
43    inner: jod_thread::Builder,
44    allow_leak: bool,
45}
46
47impl Builder {
48    #[must_use]
49    pub fn new(intent: ThreadIntent, name: impl Into<String>) -> Self {
50        Self {
51            intent,
52            inner: jod_thread::Builder::new().name(name.into()),
53            allow_leak: false,
54        }
55    }
56
57    #[must_use]
58    pub fn stack_size(self, size: usize) -> Self {
59        Self {
60            inner: self.inner.stack_size(size),
61            ..self
62        }
63    }
64
65    /// Whether dropping should detach the thread
66    /// instead of joining it.
67    #[must_use]
68    pub fn allow_leak(self, allow_leak: bool) -> Self {
69        Self { allow_leak, ..self }
70    }
71
72    pub fn spawn<F, T>(self, f: F) -> std::io::Result<JoinHandle<T>>
73    where
74        F: (FnOnce() -> T) + Send + 'static,
75        T: Send + 'static,
76    {
77        let inner_handle = self.inner.spawn(move || {
78            self.intent.apply_to_current_thread();
79            f()
80        })?;
81
82        Ok(JoinHandle {
83            inner: Some(inner_handle),
84            allow_leak: self.allow_leak,
85        })
86    }
87}
88
89pub struct JoinHandle<T = ()> {
90    // `inner` is an `Option` so that we can
91    // take ownership of the contained `JoinHandle`.
92    inner: Option<jod_thread::JoinHandle<T>>,
93    allow_leak: bool,
94}
95
96impl<T> JoinHandle<T> {
97    /// # Panics
98    ///
99    /// Panics if there is no thread to join.
100    #[must_use]
101    pub fn join(mut self) -> T {
102        self.inner.take().unwrap().join()
103    }
104}
105
106impl<T> Drop for JoinHandle<T> {
107    fn drop(&mut self) {
108        if !self.allow_leak {
109            return;
110        }
111
112        if let Some(join_handle) = self.inner.take() {
113            join_handle.detach();
114        }
115    }
116}
117
118impl<T> fmt::Debug for JoinHandle<T> {
119    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
120        f.pad("JoinHandle { .. }")
121    }
122}
squawk_thread/lib.rs

squawk_thread/
lib.rs
