Skip to main content

qos_threads/
lib.rs

1#![doc = include_str!("../README.md")]
2
3use std::fmt;
4
5/// Thread scheduling priority class for a workload's `QoS` policy.
6///
7/// The two classes encode the asymmetric "prioritize latency, throttle CPU"
8/// split: latency-sensitive threads run [`Qos::High`] so they are scheduled
9/// promptly even under load, while CPU-bound work runs [`Qos::Low`] so it
10/// yields to interactive workloads on a shared machine.
11#[derive(Debug, Clone, Copy, PartialEq, Eq)]
12pub enum Qos {
13    /// Latency-sensitive work such as network event loops, discovery,
14    /// heartbeats, and connection management.
15    /// macOS `QOS_CLASS_USER_INITIATED`; Linux nice 0 (`SCHED_OTHER`).
16    High,
17    /// CPU-bound background work such as analysis, compaction, or index
18    /// construction. macOS
19    /// `QOS_CLASS_UTILITY`; Linux nice +10.
20    Low,
21}
22
23/// An operating-system scheduling call was rejected. Carries the raw `errno`.
24///
25/// This is never returned for an unsupported platform (those are successful
26/// no-ops), only for a genuine OS rejection, such as `EPERM` when raising
27/// priority without `CAP_SYS_NICE` on Linux.
28#[derive(Debug, Clone, Copy, PartialEq, Eq)]
29pub struct QosError(i32);
30
31impl QosError {
32    /// The raw OS error number that caused the rejection.
33    #[must_use]
34    pub fn errno(self) -> i32 {
35        self.0
36    }
37}
38
39impl fmt::Display for QosError {
40    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
41        write!(f, "thread QoS change rejected (errno {})", self.0)
42    }
43}
44
45impl std::error::Error for QosError {}
46
47/// Set the **calling thread**'s scheduling class for the rest of its life.
48/// This is intended for a runtime `on_thread_start` hook that assigns a
49/// stable class to each worker thread.
50///
51/// # Errors
52///
53/// Returns [`QosError`] if the OS rejects the change (e.g. `EPERM`).
54/// On platforms without a per-thread `QoS` API this is a successful no-op.
55pub fn set_current_thread(qos: Qos) -> Result<(), QosError> {
56    imp::set(qos)
57}
58
59/// Run `f` with the calling thread temporarily set to `qos`, restoring
60/// the thread's previous class when `f` returns or unwinds.
61///
62/// Intended to wrap CPU-bound work that runs on a **reused** thread
63/// (e.g. a blocking-pool thread): lower it to [`Qos::Low`] for the
64/// duration so it cannot starve latency-sensitive threads, then hand the
65/// thread back at its prior class for the next task.
66pub fn with_qos<T>(qos: Qos, f: impl FnOnce() -> T) -> T {
67    // RAII so the previous class is restored even if `f` panics.
68    let _restore = Restore(imp::save());
69    let _ = imp::set(qos);
70    f()
71}
72
73struct Restore(imp::Saved);
74
75impl Drop for Restore {
76    fn drop(&mut self) {
77        imp::restore(&self.0);
78    }
79}
80
81/// Raise this **process**'s disk-I/O priority so durable reads and writes win
82/// contention against low-priority OS housekeeping. Process-scoped, so it
83/// also covers threads that do not use a per-thread [`Qos`] hook. Call once
84/// during process startup when durable I/O should remain responsive.
85///
86/// On macOS this uses `setiopolicy_np(IOPOL_TYPE_DISK, IOPOL_SCOPE_PROCESS,
87/// IOPOL_IMPORTANT)`. On Linux, process-wide I/O policy is normally managed
88/// by the service manager, so this function is a successful no-op.
89///
90/// # Errors
91///
92/// Returns [`QosError`] if the OS rejects the change.
93pub fn boost_process_io() -> Result<(), QosError> {
94    #[cfg(target_vendor = "apple")]
95    {
96        imp::boost_process_io()
97    }
98    #[cfg(not(target_vendor = "apple"))]
99    {
100        imp::boost_process_io();
101        Ok(())
102    }
103}
104
105#[cfg(target_vendor = "apple")]
106mod imp {
107    use libc::qos_class_t::{QOS_CLASS_DEFAULT, QOS_CLASS_USER_INITIATED, QOS_CLASS_UTILITY};
108
109    use super::{Qos, QosError};
110
111    pub(super) struct Saved {
112        class: libc::qos_class_t,
113        relative_priority: libc::c_int,
114    }
115
116    fn class_of(qos: Qos) -> libc::qos_class_t {
117        match qos {
118            Qos::High => QOS_CLASS_USER_INITIATED,
119            Qos::Low => QOS_CLASS_UTILITY,
120        }
121    }
122
123    pub(super) fn set(qos: Qos) -> Result<(), QosError> {
124        // SAFETY: `pthread_set_qos_class_self_np` acts on the calling
125        // thread, takes no pointers, and returns 0 or an errno.
126        let rc = unsafe { libc::pthread_set_qos_class_self_np(class_of(qos), 0) };
127        if rc == 0 { Ok(()) } else { Err(QosError(rc)) }
128    }
129
130    pub(super) fn save() -> Saved {
131        let mut class = QOS_CLASS_DEFAULT;
132        let mut relative_priority: libc::c_int = 0;
133        // SAFETY: writes through two valid stack pointers for the
134        // calling thread; the return code is advisory and ignored.
135        unsafe {
136            libc::pthread_get_qos_class_np(
137                libc::pthread_self(),
138                &raw mut class,
139                &raw mut relative_priority,
140            );
141        }
142        Saved {
143            class,
144            relative_priority,
145        }
146    }
147
148    pub(super) fn restore(saved: &Saved) {
149        // SAFETY: see `set`; best-effort restore, return code ignored.
150        unsafe {
151            libc::pthread_set_qos_class_self_np(saved.class, saved.relative_priority);
152        }
153    }
154
155    // IOPOL constants from `<sys/resource.h>`; `libc` does not surface them.
156    const IOPOL_TYPE_DISK: libc::c_int = 0;
157    const IOPOL_SCOPE_PROCESS: libc::c_int = 1;
158    const IOPOL_IMPORTANT: libc::c_int = 1;
159
160    unsafe extern "C" {
161        fn setiopolicy_np(
162            iotype: libc::c_int,
163            scope: libc::c_int,
164            policy: libc::c_int,
165        ) -> libc::c_int;
166    }
167
168    pub(super) fn boost_process_io() -> Result<(), QosError> {
169        // SAFETY: three scalar args, no pointers; returns 0, or -1 with
170        // errno set.
171        let rc = unsafe { setiopolicy_np(IOPOL_TYPE_DISK, IOPOL_SCOPE_PROCESS, IOPOL_IMPORTANT) };
172        if rc == 0 {
173            Ok(())
174        } else {
175            Err(QosError(
176                std::io::Error::last_os_error().raw_os_error().unwrap_or(-1),
177            ))
178        }
179    }
180}
181
182#[cfg(any(target_os = "linux", target_os = "android"))]
183mod imp {
184    use super::{Qos, QosError};
185
186    pub(super) struct Saved {
187        nice: libc::c_int,
188    }
189
190    fn nice_of(qos: Qos) -> libc::c_int {
191        match qos {
192            // Raising priority above the process baseline needs
193            // CAP_SYS_NICE; an unprivileged caller receives QosError.
194            Qos::High => 0,
195            Qos::Low => 10,
196        }
197    }
198
199    pub(super) fn set(qos: Qos) -> Result<(), QosError> {
200        // `setpriority(PRIO_PROCESS, 0, ..)` targets the calling thread
201        // on Linux (nice is per-task and `who == 0` is the caller).
202        // SAFETY: no pointers; returns 0 or -1 with errno set.
203        let rc = unsafe { libc::setpriority(libc::PRIO_PROCESS, 0, nice_of(qos)) };
204        if rc == 0 {
205            Ok(())
206        } else {
207            Err(QosError(
208                std::io::Error::last_os_error().raw_os_error().unwrap_or(-1),
209            ))
210        }
211    }
212
213    pub(super) fn save() -> Saved {
214        // For the values we set (0/10) the `-1`-means-error ambiguity of
215        // `getpriority` never applies, so the return is the nice value.
216        // SAFETY: no pointers.
217        let nice = unsafe { libc::getpriority(libc::PRIO_PROCESS, 0) };
218        Saved { nice }
219    }
220
221    pub(super) fn restore(saved: &Saved) {
222        // SAFETY: see `set`; best-effort restore, return code ignored.
223        unsafe {
224            libc::setpriority(libc::PRIO_PROCESS, 0, saved.nice);
225        }
226    }
227
228    pub(super) fn boost_process_io() {
229        // Whole-process disk-I/O priority is normally set declaratively by a
230        // Linux service manager, which covers the service cgroup regardless
231        // of when threads spawn. Nothing to do here.
232    }
233}
234
235#[cfg(not(any(target_vendor = "apple", target_os = "linux", target_os = "android")))]
236mod imp {
237    use super::{Qos, QosError};
238
239    pub(super) struct Saved;
240
241    pub(super) fn set(_qos: Qos) -> Result<(), QosError> {
242        Ok(())
243    }
244
245    pub(super) fn save() -> Saved {
246        Saved
247    }
248
249    pub(super) fn restore(_saved: &Saved) {}
250
251    pub(super) fn boost_process_io() {}
252}
253
254#[cfg(test)]
255mod tests {
256    use super::*;
257
258    /// Lowering priority never needs privilege; unsupported platforms use the
259    /// successful no-op implementation.
260    #[test]
261    fn low_and_high_apply_without_error() {
262        // Low first: always permitted everywhere.
263        assert!(set_current_thread(Qos::Low).is_ok());
264        // Raising priority may be rejected on an unprivileged Linux process.
265        let _ = set_current_thread(Qos::High);
266    }
267
268    #[test]
269    fn boost_process_io_does_not_error_on_supported_platforms() {
270        // macOS applies the native policy; Linux and other platforms use the
271        // service-manager/no-op implementation.
272        assert!(boost_process_io().is_ok());
273    }
274
275    #[test]
276    fn with_qos_returns_closure_value_and_runs_it() {
277        let mut ran = false;
278        let out = with_qos(Qos::Low, || {
279            ran = true;
280            7 + 35
281        });
282        assert!(ran);
283        assert_eq!(out, 42);
284    }
285
286    #[test]
287    fn with_qos_nests() {
288        let out = with_qos(Qos::High, || with_qos(Qos::Low, || "inner").len());
289        assert_eq!(out, 5);
290    }
291
292    #[test]
293    fn with_qos_restores_after_panic() {
294        let result = std::panic::catch_unwind(|| {
295            with_qos(Qos::Low, || panic!("boom"));
296        });
297        assert!(result.is_err());
298        // The Restore guard ran during unwind; a subsequent set still works.
299        assert!(set_current_thread(Qos::Low).is_ok());
300    }
301
302    #[test]
303    fn qos_error_reports_errno() {
304        let err = QosError(13);
305        assert_eq!(err.errno(), 13);
306        assert!(err.to_string().contains("13"));
307    }
308}