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}