Files
horizon-airdef/crates/horizon-threads/src/lib.rs
T
Ludovic Marie 59d6b525ce Merge pull request #2116 from kacpherek/fix/2095-signal-save
🤖 Agent: Read against the vanilla 26.3 sources (Save the world on SIGTERM, Ctrl+C and SIGHUP) and proven in contrib-gate-21's union of 72 kacpherek PRs: 95 parity harnesses on playhorizon and the Mac mini, clippy, 1534 tests, lan_e2e 23 checks in-frame and with --server-thread. Thanks @kacpherek!
2026-10-27 11:12:54 +01:00

304 lines
12 KiB
Rust

//! Scheduling hints for the game's threads: the few OS calls that the other
//! crates, which forbid unsafe code, can't make themselves.
use std::sync::atomic::{AtomicBool, Ordering};
/// Ask the OS to run the calling thread ahead of the process's other
/// threads, as vanilla's `MinecraftServer.spin` does for its server thread
/// (`Thread.setPriority(8)` when there are more than four processors), so
/// world generation and chunk encoding on every other core don't hold a tick
/// back (the client asks the same for its render thread, so they don't hold
/// a frame back either): user-interactive quality of service on macOS,
/// above-normal priority on Windows. Nothing elsewhere: Linux lets an
/// unprivileged thread lower its priority but not raise it (and the JVM
/// leaves it there too). Whether the OS took it.
pub fn favour_current() -> bool {
if std::thread::available_parallelism().map_or(1, |n| n.get()) <= 4 {
return false;
}
favour()
}
#[cfg(target_vendor = "apple")]
fn favour() -> bool {
// SAFETY: sets the calling thread's own QoS class; no pointers.
unsafe {
libc::pthread_set_qos_class_self_np(libc::qos_class_t::QOS_CLASS_USER_INTERACTIVE, 0) == 0
}
}
#[cfg(windows)]
fn favour() -> bool {
use windows_sys::Win32::System::Threading::{
GetCurrentThread, SetThreadPriority, THREAD_PRIORITY_ABOVE_NORMAL,
};
// SAFETY: GetCurrentThread's pseudo handle needs no closing.
unsafe { SetThreadPriority(GetCurrentThread(), THREAD_PRIORITY_ABOVE_NORMAL) != 0 }
}
#[cfg(not(any(target_vendor = "apple", windows)))]
fn favour() -> bool {
false
}
/// The CPU time the calling thread has used, where only an OS call gives it
/// precisely. Windows counts it exactly only in cycles of the time-stamp
/// counter (`QueryThreadCycleTime`; `GetThreadTimes` moves in scheduler ticks
/// of ~15.6 ms), so the counter's rate is measured once against the wall
/// clock and cycles convert to time. `None` elsewhere: unix callers read
/// `CLOCK_THREAD_CPUTIME_ID` themselves.
#[cfg(all(windows, target_arch = "x86_64"))]
pub fn thread_cpu() -> Option<std::time::Duration> {
use std::{
sync::OnceLock,
time::{Duration, Instant},
};
use windows_sys::Win32::System::{
Threading::GetCurrentThread, WindowsProgramming::QueryThreadCycleTime,
};
// Time-stamp counter cycles per nanosecond.
static RATE: OnceLock<f64> = OnceLock::new();
let rate = *RATE.get_or_init(|| {
// SAFETY: RDTSC has no preconditions on x86_64.
let tsc = || unsafe { core::arch::x86_64::_rdtsc() };
let (wall, start) = (Instant::now(), tsc());
std::thread::sleep(Duration::from_millis(20));
(tsc() - start) as f64 / wall.elapsed().as_nanos() as f64
});
let mut cycles = 0;
// SAFETY: GetCurrentThread's pseudo handle needs no closing; a valid out pointer.
if unsafe { QueryThreadCycleTime(GetCurrentThread(), &mut cycles) } == 0 {
return None;
}
Some(Duration::from_nanos((cycles as f64 / rate) as u64))
}
#[cfg(not(all(windows, target_arch = "x86_64")))]
pub fn thread_cpu() -> Option<std::time::Duration> {
None
}
/// Set once as the game starts, before its helper threads do: they then go
/// behind the server thread and the render thread (`behind_server`).
static HELPERS_BEHIND: AtomicBool = AtomicBool::new(false);
/// How many nice levels a helper thread goes below the process on Linux and Android.
#[cfg(any(target_os = "linux", target_os = "android"))]
const BEHIND: i32 = 10;
/// From now on, the helper threads that call `behind_server` as they start
/// go behind the server thread (a dedicated server's or single player's)
/// and the render thread. Call it before they start.
pub fn put_helpers_behind() {
HELPERS_BEHIND.store(true, Ordering::Relaxed);
}
/// Called by a helper thread as it starts (world generation, lighting and
/// meshing, a connection's packet writer): work no tick or frame waits for.
/// Once `put_helpers_behind` was called, on Linux and Android, where the server and
/// render threads can't be raised (`favour_current`), the helper lowers
/// itself instead, which an unprivileged thread may: 10 nice levels below
/// the process, or, where nice runs out (a game started under nice 10 or
/// more), the idle class, which runs the thread only when no ordinary thread
/// wants its core. A tick or a frame then gets a core when it starts instead
/// of waiting behind them. Nothing elsewhere. Whether the OS took it.
pub fn behind_server() -> bool {
HELPERS_BEHIND.load(Ordering::Relaxed) && behind()
}
#[cfg(any(target_os = "linux", target_os = "android"))]
fn behind() -> bool {
// SAFETY: these read and set the calling thread's own nice value or
// policy (who 0, pid 0 is the calling thread on Linux and Android); `param` lives
// across the call.
unsafe {
let nice = libc::getpriority(libc::PRIO_PROCESS as _, 0);
if nice + BEHIND <= 19 {
libc::setpriority(libc::PRIO_PROCESS as _, 0, nice + BEHIND) == 0
} else {
let param = libc::sched_param { sched_priority: 0 };
libc::sched_setscheduler(0, libc::SCHED_IDLE, &param) == 0
}
}
}
#[cfg(not(any(target_os = "linux", target_os = "android")))]
fn behind() -> bool {
false
}
/// Run the calling thread only on a core nothing else wants: work that may
/// take seconds and that nothing waits for yet (the stronghold rings while a
/// world opens). The idle class on Linux, background quality of service on
/// macOS, idle priority on Windows. Whether the OS took it.
pub fn idle_current() -> bool {
idle()
}
#[cfg(target_os = "linux")]
fn idle() -> bool {
let param = libc::sched_param { sched_priority: 0 };
// SAFETY: sets the calling thread's own policy (pid 0); `param` lives
// across the call.
unsafe { libc::sched_setscheduler(0, libc::SCHED_IDLE, &param) == 0 }
}
#[cfg(target_vendor = "apple")]
fn idle() -> bool {
// SAFETY: sets the calling thread's own QoS class; no pointers.
unsafe { libc::pthread_set_qos_class_self_np(libc::qos_class_t::QOS_CLASS_BACKGROUND, 0) == 0 }
}
#[cfg(windows)]
fn idle() -> bool {
use windows_sys::Win32::System::Threading::{
GetCurrentThread, SetThreadPriority, THREAD_PRIORITY_IDLE,
};
// SAFETY: GetCurrentThread's pseudo handle needs no closing.
unsafe { SetThreadPriority(GetCurrentThread(), THREAD_PRIORITY_IDLE) != 0 }
}
#[cfg(not(any(target_os = "linux", target_vendor = "apple", windows)))]
fn idle() -> bool {
false
}
/// How many stop requests (Ctrl-C, SIGTERM, SIGHUP) arrived since `catch_stop_signals`.
pub fn stop_requests() -> u32 {
STOP_REQUESTS.load(std::sync::atomic::Ordering::SeqCst)
}
static STOP_REQUESTS: std::sync::atomic::AtomicU32 = std::sync::atomic::AtomicU32::new(0);
/// Count stop requests from outside instead of dying on them: vanilla's "Client Shutdown Thread"
/// (`Main.java`) halts the integrated server when the JVM shuts down, and the JVM does that on
/// these signals, so a killed game still saves. The caller's event loop turns the first request
/// into a normal quit; a second one (the save is stuck) ends the process at once.
#[cfg(any(target_vendor = "apple", target_os = "linux", target_os = "android"))]
pub fn catch_stop_signals() {
extern "C" fn handle(_: libc::c_int) {
if STOP_REQUESTS.fetch_add(1, Ordering::SeqCst) >= 1 {
// SAFETY: _exit is async-signal-safe; 130 is the shell's code for a Ctrl-C death.
unsafe { libc::_exit(130) }
}
}
let handler = handle as extern "C" fn(libc::c_int);
for signal in [libc::SIGINT, libc::SIGTERM, libc::SIGHUP] {
// SAFETY: the handler only touches an atomic and calls _exit, both async-signal-safe.
unsafe {
libc::signal(signal, handler as libc::sighandler_t);
}
}
}
/// Windows and the other systems keep their default: a closed window is a `CloseRequested`.
#[cfg(not(any(target_vendor = "apple", target_os = "linux", target_os = "android")))]
pub fn catch_stop_signals() {}
/// Give back to the OS the memory the allocator holds free, after something
/// large was dropped: glibc keeps freed pages in the arena of the thread that
/// allocated them, and macOS in its zones until memory runs short. Nothing
/// elsewhere.
pub fn release_free_memory() {
release();
}
#[cfg(all(target_os = "linux", target_env = "gnu"))]
fn release() {
// SAFETY: returns free heap pages of every arena to the OS; no live
// allocation moves.
unsafe {
libc::malloc_trim(0);
}
}
#[cfg(target_vendor = "apple")]
fn release() {
unsafe extern "C" {
fn malloc_zone_pressure_relief(zone: *mut std::ffi::c_void, goal: usize) -> usize;
}
// SAFETY: a null zone means every zone and a goal of 0 as much as it can;
// it frees only pages no allocation uses.
unsafe {
malloc_zone_pressure_relief(std::ptr::null_mut(), 0);
}
}
#[cfg(not(any(all(target_os = "linux", target_env = "gnu"), target_vendor = "apple")))]
fn release() {}
#[cfg(test)]
mod tests {
/// The hint holds on the platforms that take it.
#[test]
fn favouring_a_thread_takes_where_the_os_allows_it() {
let took = std::thread::spawn(super::favour).join().unwrap();
assert_eq!(took, cfg!(any(target_vendor = "apple", windows)));
#[cfg(target_vendor = "apple")]
std::thread::spawn(|| {
assert!(super::favour());
let mut class = libc::qos_class_t::QOS_CLASS_UNSPECIFIED;
let mut relative = 0;
// SAFETY: reads the calling thread's own QoS class into locals.
let read = unsafe {
libc::pthread_get_qos_class_np(libc::pthread_self(), &mut class, &mut relative)
};
assert_eq!(read, 0);
assert!(matches!(
class,
libc::qos_class_t::QOS_CLASS_USER_INTERACTIVE
));
})
.join()
.unwrap();
}
/// A helper goes behind only once a dedicated server asks for it, and
/// then, on Linux and Android, 10 nice levels below the process or in the idle class.
#[test]
fn helpers_go_behind_only_when_asked() {
assert!(!std::thread::spawn(super::behind_server).join().unwrap());
super::put_helpers_behind();
#[cfg(any(target_os = "linux", target_os = "android"))]
std::thread::spawn(|| {
// SAFETY: reads the calling thread's own nice value.
let before = unsafe { libc::getpriority(libc::PRIO_PROCESS as _, 0) };
assert!(super::behind_server());
// SAFETY: reads the calling thread's own nice value and policy.
let (after, policy) = unsafe {
(
libc::getpriority(libc::PRIO_PROCESS as _, 0),
libc::sched_getscheduler(0),
)
};
if before + super::BEHIND <= 19 {
assert_eq!(after, before + super::BEHIND);
} else {
assert_eq!(policy, libc::SCHED_IDLE);
}
})
.join()
.unwrap();
#[cfg(not(any(target_os = "linux", target_os = "android")))]
assert!(!std::thread::spawn(super::behind_server).join().unwrap());
}
/// The idle hint holds on the three platforms.
#[test]
fn idling_a_thread_takes() {
let took = std::thread::spawn(super::idle_current).join().unwrap();
assert_eq!(
took,
cfg!(any(target_os = "linux", target_vendor = "apple", windows))
);
#[cfg(target_os = "linux")]
std::thread::spawn(|| {
assert!(super::idle_current());
// SAFETY: reads the calling thread's own policy.
assert_eq!(unsafe { libc::sched_getscheduler(0) }, libc::SCHED_IDLE);
})
.join()
.unwrap();
}
}