qualia_core_db/platform/platform_scheduler.rs
1//! Platform-aware thread QoS and core-affinity binding.
2//!
3//! Binds the calling thread to the most appropriate processor class for its
4//! workload so the OS scheduler makes the right placement decision:
5//!
6//! | Class | macOS QoS | Linux | Windows |
7//! |--------------------|----------------------------|-------------------|----------------------------|
8//! | UserInteractive | QOS_CLASS_USER_INTERACTIVE | P-cores (affinity)| THREAD_PRIORITY_HIGHEST |
9//! | UserInitiated | QOS_CLASS_USER_INITIATED | P-cores | THREAD_PRIORITY_ABOVE_NORMAL|
10//! | Default | QOS_CLASS_DEFAULT | any | THREAD_PRIORITY_NORMAL |
11//! | Utility | QOS_CLASS_UTILITY | any | THREAD_PRIORITY_BELOW_NORMAL|
12//! | Background | QOS_CLASS_BACKGROUND | E-cores (affinity)| THREAD_PRIORITY_IDLE |
13//!
14//! **Apple Silicon AMP** (P-cores + E-cores) is the primary target.
15//! On Intel/AMD/ARM64 the distinction collapses to thread priority.
16
17#![cfg(not(target_arch = "wasm32"))]
18
19// ──────────────────────────────────────────────────────────────────────────────
20// Darwin QoS FFI
21// ──────────────────────────────────────────────────────────────────────────────
22
23#[cfg(target_os = "macos")]
24mod darwin_qos {
25 /// QoS class values from <sys/qos.h> (Darwin 18+).
26 pub const QOS_CLASS_USER_INTERACTIVE: u32 = 0x21; // 33
27 pub const QOS_CLASS_USER_INITIATED: u32 = 0x19; // 25
28 pub const QOS_CLASS_DEFAULT: u32 = 0x15; // 21
29 pub const QOS_CLASS_UTILITY: u32 = 0x11; // 17
30 pub const QOS_CLASS_BACKGROUND: u32 = 0x09; // 9
31
32 extern "C" {
33 /// Set the QoS class of the calling thread.
34 /// `relative_priority` must be in `[QOS_MIN_RELATIVE_PRIORITY, 0]`
35 /// where `QOS_MIN_RELATIVE_PRIORITY = -15`.
36 pub fn pthread_set_qos_class_self_np(
37 qos_class: u32,
38 relative_priority: libc::c_int,
39 ) -> libc::c_int;
40
41 /// Read back the QoS class of any thread (NULL → calling thread).
42 pub fn pthread_get_qos_class_np(
43 thread: libc::pthread_t,
44 qos_class_out: *mut u32,
45 relative_priority_out: *mut libc::c_int,
46 ) -> libc::c_int;
47 }
48}
49
50// ──────────────────────────────────────────────────────────────────────────────
51// Public API
52// ──────────────────────────────────────────────────────────────────────────────
53
54#[derive(Debug, Clone, Copy, PartialEq, Eq)]
55pub enum QosClass {
56 /// LLM inference, active SPARQL queries, Phase 8 decode loop.
57 /// → Apple P-cores / Windows HIGHEST / Linux P-core affinity.
58 UserInteractive,
59 /// Active user requests, graph engine hot path.
60 UserInitiated,
61 /// Default — no preference.
62 Default,
63 /// Background sync, slow I/O.
64 Utility,
65 /// WAL flush, Merkle root computation, ambient orchestration.
66 /// → Apple E-cores / Windows IDLE / Linux E-core affinity.
67 Background,
68}
69
70#[derive(Debug)]
71pub enum SchedulerError {
72 Unsupported(String),
73 OsError(i32),
74}
75
76impl std::fmt::Display for SchedulerError {
77 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
78 match self {
79 SchedulerError::Unsupported(m) => write!(f, "unsupported: {m}"),
80 SchedulerError::OsError(e) => write!(f, "OS error {e}"),
81 }
82 }
83}
84
85/// Bind the **calling thread** to `class`.
86///
87/// Returns `Ok(())` if the platform supports QoS binding, or
88/// `Err(SchedulerError::Unsupported)` on platforms that have no thread
89/// priority API (rare).
90pub fn bind_current_thread(class: QosClass) -> Result<(), SchedulerError> {
91 bind_macos(class)
92 .or_else(|_| bind_linux(class))
93 .or_else(|_| bind_windows(class))
94}
95
96/// Convenience wrapper: bind to UserInteractive (P-core / max priority).
97/// Call from the LLM inference thread and active SPARQL query thread.
98pub fn bind_inference_thread() {
99 let _ = bind_current_thread(QosClass::UserInteractive);
100}
101
102/// Convenience wrapper: bind to Background (E-core / idle priority).
103/// Call from WAL flush, Merkle DAG, ambient orchestration threads.
104pub fn bind_background_thread() {
105 let _ = bind_current_thread(QosClass::Background);
106}
107
108// ──────────────────────────────────────────────────────────────────────────────
109// macOS implementation
110// ──────────────────────────────────────────────────────────────────────────────
111
112fn bind_macos(#[allow(unused_variables)] class: QosClass) -> Result<(), SchedulerError> {
113 #[cfg(target_os = "macos")]
114 {
115 use darwin_qos::*;
116 let qos = match class {
117 QosClass::UserInteractive => QOS_CLASS_USER_INTERACTIVE,
118 QosClass::UserInitiated => QOS_CLASS_USER_INITIATED,
119 QosClass::Default => QOS_CLASS_DEFAULT,
120 QosClass::Utility => QOS_CLASS_UTILITY,
121 QosClass::Background => QOS_CLASS_BACKGROUND,
122 };
123 // SAFETY: pthread_set_qos_class_self_np is safe to call from any thread.
124 let rc = unsafe { pthread_set_qos_class_self_np(qos, 0) };
125 if rc == 0 {
126 return Ok(());
127 }
128 return Err(SchedulerError::OsError(rc));
129 }
130 #[cfg(not(target_os = "macos"))]
131 Err(SchedulerError::Unsupported(
132 "macOS QoS not available on this platform".into(),
133 ))
134}
135
136// ──────────────────────────────────────────────────────────────────────────────
137// Linux implementation — core_affinity for asymmetric multiprocessing
138// ──────────────────────────────────────────────────────────────────────────────
139
140fn bind_linux(#[allow(unused_variables)] class: QosClass) -> Result<(), SchedulerError> {
141 #[cfg(target_os = "linux")]
142 {
143 let all_cores = core_affinity::get_core_ids()
144 .ok_or_else(|| SchedulerError::Unsupported("core_affinity unavailable".into()))?;
145
146 if all_cores.is_empty() {
147 return Err(SchedulerError::Unsupported("no cores found".into()));
148 }
149
150 // Heuristic for big.LITTLE / Alder Lake / Sapphire Rapids:
151 // Lower-numbered cores are P-cores; higher-numbered are E-cores.
152 // We split at the midpoint as a conservative estimate.
153 let mid = all_cores.len() / 2;
154 let target = match class {
155 QosClass::UserInteractive | QosClass::UserInitiated => {
156 // P-cores: first half (or all if symmetric)
157 &all_cores[..mid.max(1)]
158 }
159 QosClass::Background | QosClass::Utility => {
160 // E-cores: second half (or all if symmetric)
161 &all_cores[mid..]
162 }
163 QosClass::Default => &all_cores[..],
164 };
165
166 // Pin to the first core in the target set; real production code would
167 // use `sched_setaffinity` with a full mask, but core_affinity exposes
168 // single-core pinning which is sufficient for the inference split.
169 if let Some(core) = target.first() {
170 if core_affinity::set_for_current(*core) {
171 return Ok(());
172 }
173 }
174
175 // Also set Linux thread nice / scheduling policy.
176 let nice_val: libc::c_int = match class {
177 QosClass::UserInteractive => -10,
178 QosClass::UserInitiated => -5,
179 QosClass::Default => 0,
180 QosClass::Utility => 5,
181 QosClass::Background => 19,
182 };
183 // SAFETY: getpid() always succeeds; setpriority is safe with valid args.
184 unsafe {
185 libc::setpriority(libc::PRIO_PROCESS, 0, nice_val);
186 }
187 return Ok(());
188 }
189 #[cfg(not(target_os = "linux"))]
190 Err(SchedulerError::Unsupported(
191 "Linux sched_setaffinity not available".into(),
192 ))
193}
194
195// ──────────────────────────────────────────────────────────────────────────────
196// Windows implementation — SetThreadPriority
197// ──────────────────────────────────────────────────────────────────────────────
198
199fn bind_windows(#[allow(unused_variables)] class: QosClass) -> Result<(), SchedulerError> {
200 #[cfg(all(target_os = "windows", target_arch = "x86_64"))]
201 {
202 use windows::Win32::System::Threading::{
203 GetCurrentThread, SetThreadPriority, THREAD_PRIORITY_ABOVE_NORMAL,
204 THREAD_PRIORITY_BELOW_NORMAL, THREAD_PRIORITY_HIGHEST, THREAD_PRIORITY_IDLE,
205 THREAD_PRIORITY_NORMAL,
206 };
207 let priority = match class {
208 QosClass::UserInteractive => THREAD_PRIORITY_HIGHEST,
209 QosClass::UserInitiated => THREAD_PRIORITY_ABOVE_NORMAL,
210 QosClass::Default => THREAD_PRIORITY_NORMAL,
211 QosClass::Utility => THREAD_PRIORITY_BELOW_NORMAL,
212 QosClass::Background => THREAD_PRIORITY_IDLE,
213 };
214 // SAFETY: GetCurrentThread() returns a pseudo-handle that is always valid.
215 let ok = unsafe { SetThreadPriority(GetCurrentThread(), priority) };
216 return if ok.is_ok() {
217 Ok(())
218 } else {
219 Err(SchedulerError::OsError(
220 unsafe { windows::Win32::Foundation::GetLastError() }.0 as i32,
221 ))
222 };
223 }
224 #[cfg(not(all(target_os = "windows", target_arch = "x86_64")))]
225 Err(SchedulerError::Unsupported(
226 "Windows SetThreadPriority not available".into(),
227 ))
228}
229
230// ──────────────────────────────────────────────────────────────────────────────
231// Query current QoS (macOS only)
232// ──────────────────────────────────────────────────────────────────────────────
233
234/// Read the QoS class of the calling thread. Returns `None` on non-macOS.
235pub fn current_qos_class() -> Option<u32> {
236 #[cfg(target_os = "macos")]
237 {
238 let mut cls: u32 = 0;
239 let mut rel: libc::c_int = 0;
240 // SAFETY: pthread_get_qos_class_np with null thread → calling thread.
241 let rc = unsafe {
242 darwin_qos::pthread_get_qos_class_np(libc::pthread_self(), &mut cls, &mut rel)
243 };
244 if rc == 0 {
245 Some(cls)
246 } else {
247 None
248 }
249 }
250 #[cfg(not(target_os = "macos"))]
251 None
252}
253
254// ──────────────────────────────────────────────────────────────────────────────
255// Tests
256// ──────────────────────────────────────────────────────────────────────────────
257
258#[cfg(test)]
259mod tests {
260 use super::*;
261
262 #[test]
263 fn test_bind_does_not_panic() {
264 // On every platform this must complete without panic.
265 // It may return Err(Unsupported) on platforms with no QoS API.
266 let _ = bind_current_thread(QosClass::UserInteractive);
267 let _ = bind_current_thread(QosClass::Background);
268 }
269
270 #[test]
271 fn test_inference_background_helpers() {
272 bind_inference_thread();
273 bind_background_thread();
274 }
275
276 #[test]
277 fn test_current_qos_no_panic() {
278 let _ = current_qos_class(); // May return None on non-macOS
279 }
280}