Minecraft: Java Edition 26.3 rewritten from scratch in Rust, checked against vanilla with 281 differential harnesses. Get it with the Horizon launcher.
Rust differential-testinggame-enginegamedevlinuxminecraftminecraft-javareimplementationrustvoxelvulkanwgpu
//! The player's cap on the memory the game holds, and the last resort behind it.
//!
//! On Windows the system enforces it: a hard working set limit never lets the game hold more in
//! RAM, and moves what it used least out instead of failing, so a low cap costs speed. Elsewhere
//! no such limit exists, and the game keeps itself under the cap by holding less
//! (`horizon_client::ram_limit`, which reads [`pressure`]).
//!
//! A watcher thread reads the process's resident memory and, over the cap, gives free pages back.
//! Only when the game has nothing left to give up ([`can_shrink`] has stopped being called) and
//! stays over for [`GRACE`] does it call the game's `exceeded`. A cap the system enforces can't be
//! gone over, so there the sign is a game frozen by it: no [`frame`] for [`STALL`] while it faults
//! hard. No thread runs until a cap is set, and there is no lowest cap: one the game can't live
//! under ends the game.
use std::sync::atomic::{AtomicU64, Ordering};
use std::sync::{Once, OnceLock};
use std::time::{Duration, Instant};
const NONE: u64 = u64::MAX;
const EVERY: Duration = Duration::from_secs(1);
/// How long the game may stay over the cap with nothing left to give up: a world's first chunks,
/// or a burst the last step down has not freed yet, pass within it.
pub const GRACE: Duration = Duration::from_secs(20);
/// How long a game may draw nothing while faulting hard under a cap the system enforces.
pub const STALL: Duration = Duration::from_secs(60);
/// Page faults a second that say a game drawing nothing is busy fetching memory back, not just
/// minimized or waiting.
#[cfg_attr(not(windows), allow(dead_code))]
const STALL_FAULTS: f64 = 20_000.;
/// How long one [`can_shrink`] counts for.
const SHRINK_WORD: Duration = Duration::from_secs(5);
static LIMIT: AtomicU64 = AtomicU64::new(NONE);
static WATCHER: Once = Once::new();
static STARTED: OnceLock<Instant> = OnceLock::new();
/// Until when, in milliseconds since [`STARTED`], the game says it can still shrink.
static SHRINKS_UNTIL: AtomicU64 = AtomicU64::new(0);
/// When the last [`frame`] was, in milliseconds since [`STARTED`].
static LAST_FRAME: AtomicU64 = AtomicU64::new(0);
fn since_start() -> u64 {
STARTED.get_or_init(Instant::now).elapsed().as_millis() as u64
}
/// The game drew a frame.
pub fn frame() {
LAST_FRAME.store(since_start(), Ordering::Relaxed);
}
/// The game can still hold less. Said again every second while that is true, so it ends by itself
/// when the world closes.
pub fn can_shrink() {
let until = since_start() + SHRINK_WORD.as_millis() as u64;
SHRINKS_UNTIL.store(until, Ordering::Relaxed);
}
/// Sets the cap in bytes, or removes it. `exceeded(used, limit)` runs on the watcher thread when
/// the game can't get under the cap; only the first call's function is kept.
pub fn set(limit: Option<u64>, exceeded: fn(u64, u64)) {
LIMIT.store(limit.unwrap_or(NONE), Ordering::Relaxed);
// A new cap gets the whole of STALL.
frame();
system_cap(limit);
if limit.is_some() {
WATCHER.call_once(|| {
let watcher = std::thread::Builder::new()
.name("Memory limit".into())
.spawn(move || {
let mut over = Over::default();
let mut faults = Faults::default();
loop {
std::thread::sleep(EVERY);
let per_second = faults.per_second();
let limit = get();
over.follow(limit);
if let Some(limit) = limit {
check(&mut over, per_second, limit, exceeded);
}
}
});
if let Err(e) = watcher {
eprintln!("The memory limit can't be watched: {e}");
}
});
}
}
/// The cap in bytes, if one is set.
pub fn get() -> Option<u64> {
Some(LIMIT.load(Ordering::Relaxed)).filter(|limit| *limit != NONE)
}
/// How tight memory is for the game.
#[derive(Clone, Copy, Debug, PartialEq)]
pub enum Pressure {
/// It should hold less; `keep` is the share of what it holds to aim for.
Over {
keep: f64,
},
/// It could hold more.
Room,
Steady,
}
/// Against a cap nothing enforces: what the game holds. It should act before it gets there.
fn pressure_of_usage(used: u64, limit: u64) -> Pressure {
if used > limit / 10 * 9 {
Pressure::Over {
keep: limit as f64 * 0.8 / used as f64,
}
} else if used < limit / 10 * 7 {
Pressure::Room
} else {
Pressure::Steady
}
}
/// Under a cap the system enforces the game sits at the cap whether it needs the memory or not, so
/// usage says nothing: how often it has to fetch back what was moved out does. Measured on a real
/// game loading chunks at 30 frames a second: 30,000-50,000 page faults a second with no cap or any
/// cap down to 500 MB, 140,000 at 300 MB, 290,000 at 150 MB. Loading chunks fast faults a lot too,
/// so `horizon_client::ram_limit` also asks whether frames are suffering.
#[cfg_attr(not(windows), allow(dead_code))]
fn pressure_of_faults(per_second: f64) -> Pressure {
if per_second > 200_000. {
Pressure::Over { keep: 0.8 }
} else if per_second < 75_000. {
Pressure::Room
} else {
Pressure::Steady
}
}
/// How tight memory is under `limit`. Reads a difference since the last call: call it once a
/// second, from one place.
pub fn pressure(limit: u64) -> Pressure {
#[cfg(windows)]
if SYSTEM_CAP.load(Ordering::Relaxed) {
// The first reading has nothing to compare with.
static FAULTS: std::sync::Mutex<Faults> = std::sync::Mutex::new(Faults::new());
let per_second = FAULTS.lock().ok().and_then(|mut f| f.per_second());
return per_second.map_or(Pressure::Steady, pressure_of_faults);
}
resident_bytes().map_or(Pressure::Steady, |used| pressure_of_usage(used, limit))
}
/// Whether the system itself holds the game under the cap.
pub fn system_enforced() -> bool {
#[cfg(windows)]
return SYSTEM_CAP.load(Ordering::Relaxed);
#[cfg(not(windows))]
false
}
/// How long the game has been over the cap with nothing left to give up.
#[derive(Default)]
struct Over {
since: Option<Instant>,
/// The cap the grace is counted against.
limit: Option<u64>,
}
impl Over {
/// A cap turned off, or set to another value, starts its grace again.
fn follow(&mut self, limit: Option<u64>) {
if limit != self.limit {
self.since = None;
self.limit = limit;
}
}
/// Whether this reading ends the game.
fn gave_up(&mut self, now: Instant, over: bool, can_shrink: bool) -> bool {
if !over || can_shrink {
self.since = None;
return false;
}
now.duration_since(*self.since.get_or_insert(now)) >= GRACE
}
}
/// Whether a game has frozen under a cap the system enforces.
fn frozen(no_frame_for: Duration, faults_per_second: f64) -> bool {
no_frame_for >= STALL && faults_per_second >= STALL_FAULTS
}
fn check(state: &mut Over, faults: Option<f64>, limit: u64, exceeded: fn(u64, u64)) {
let Some(mut used) = resident_bytes() else {
return;
};
if system_enforced() {
let no_frame_for = since_start().saturating_sub(LAST_FRAME.load(Ordering::Relaxed));
if frozen(Duration::from_millis(no_frame_for), faults.unwrap_or(0.)) {
// The report has to be written, which a frozen game can't do under the cap.
system_cap(None);
exceeded(used, limit);
}
return;
}
if used > limit {
crate::release_free_memory();
used = resident_bytes().unwrap_or(used);
}
let can_shrink = since_start() < SHRINKS_UNTIL.load(Ordering::Relaxed);
if state.gave_up(Instant::now(), used > limit, can_shrink) {
exceeded(used, limit);
}
}
/// Whether the system is enforcing the cap.
#[cfg(windows)]
static SYSTEM_CAP: std::sync::atomic::AtomicBool = std::sync::atomic::AtomicBool::new(false);
/// Sets the system's hard limit on the working set, or lifts it. Refused (a cap below what the
/// system allows), the watcher treats the game as any other that can't get under its cap.
#[cfg(windows)]
fn system_cap(limit: Option<u64>) {
use windows_sys::Win32::System::Memory::{
QUOTA_LIMITS_HARDWS_MAX_DISABLE, QUOTA_LIMITS_HARDWS_MAX_ENABLE,
QUOTA_LIMITS_HARDWS_MIN_DISABLE, SetProcessWorkingSetSizeEx,
};
use windows_sys::Win32::System::Threading::GetCurrentProcess;
const MINIMUM: u64 = 16 << 20;
// Windows' own defaults for a process, with the limit lifted.
let (low, high, flags) = match limit {
Some(limit) => (
MINIMUM.min(limit / 2) as usize,
usize::try_from(limit).unwrap_or(usize::MAX),
QUOTA_LIMITS_HARDWS_MAX_ENABLE | QUOTA_LIMITS_HARDWS_MIN_DISABLE,
),
None => (
200 << 10,
1380 << 10,
QUOTA_LIMITS_HARDWS_MAX_DISABLE | QUOTA_LIMITS_HARDWS_MIN_DISABLE,
),
};
// SAFETY: passes plain values; the current process's pseudo-handle needs no closing.
let done = unsafe { SetProcessWorkingSetSizeEx(GetCurrentProcess(), low, high, flags) != 0 };
if !done {
eprintln!(
"Windows refused the memory limit: {}",
std::io::Error::last_os_error()
);
}
SYSTEM_CAP.store(done && limit.is_some(), Ordering::Relaxed);
}
#[cfg(not(windows))]
fn system_cap(_limit: Option<u64>) {}
/// The process's memory counters.
#[cfg(windows)]
fn counters() -> Option<windows_sys::Win32::System::ProcessStatus::PROCESS_MEMORY_COUNTERS> {
use windows_sys::Win32::System::ProcessStatus::{
K32GetProcessMemoryInfo, PROCESS_MEMORY_COUNTERS,
};
use windows_sys::Win32::System::Threading::GetCurrentProcess;
let size = std::mem::size_of::<PROCESS_MEMORY_COUNTERS>() as u32;
// SAFETY: all-zero is a valid value of this plain C struct, and the call writes at most `size`
// bytes into it; the current process's pseudo-handle needs no closing.
unsafe {
let mut counters: PROCESS_MEMORY_COUNTERS = std::mem::zeroed();
counters.cb = size;
(K32GetProcessMemoryInfo(GetCurrentProcess(), &mut counters, size) != 0).then_some(counters)
}
}
/// Page fault rates, between one reading and the next.
#[derive(Default)]
struct Faults {
#[cfg(windows)]
last: Option<(Instant, u32)>,
}
impl Faults {
#[cfg(windows)]
const fn new() -> Self {
Faults { last: None }
}
/// Page faults a second since the last call; none on the first, or where they aren't known.
#[cfg(windows)]
fn per_second(&mut self) -> Option<f64> {
let faults = counters()?.PageFaultCount;
let now = Instant::now();
let before = self.last.replace((now, faults))?;
let seconds = now.duration_since(before.0).as_secs_f64();
(seconds > 0.).then(|| f64::from(faults.wrapping_sub(before.1)) / seconds)
}
#[cfg(not(windows))]
fn per_second(&mut self) -> Option<f64> {
None
}
}
/// The memory this process holds in RAM, in bytes.
#[cfg(windows)]
pub fn resident_bytes() -> Option<u64> {
Some(counters()?.WorkingSetSize as u64)
}
/// The memory this process holds in RAM, in bytes.
#[cfg(any(target_os = "linux", target_os = "android"))]
pub fn resident_bytes() -> Option<u64> {
let statm = std::fs::read_to_string("/proc/self/statm").ok()?;
let pages: u64 = statm.split_whitespace().nth(1)?.parse().ok()?;
// SAFETY: reads one system constant.
let page = unsafe { libc::sysconf(libc::_SC_PAGESIZE) };
Some(pages * u64::try_from(page).ok()?)
}
/// The memory this process holds in RAM, in bytes.
#[cfg(target_vendor = "apple")]
pub fn resident_bytes() -> Option<u64> {
let size = std::mem::size_of::<libc::proc_taskinfo>() as libc::c_int;
// SAFETY: all-zero is a valid value of this plain C struct, and the call writes at most `size`
// bytes into it.
unsafe {
let mut info: libc::proc_taskinfo = std::mem::zeroed();
let written = libc::proc_pidinfo(
libc::getpid(),
libc::PROC_PIDTASKINFO,
0,
(&raw mut info).cast(),
size,
);
(written == size).then_some(info.pti_resident_size)
}
}
/// The memory this process holds in RAM, in bytes: not known on this system.
#[cfg(not(any(
windows,
target_os = "linux",
target_os = "android",
target_vendor = "apple"
)))]
pub fn resident_bytes() -> Option<u64> {
None
}
#[cfg(all(test, any(windows, target_os = "linux", target_vendor = "apple")))]
mod tests {
use super::*;
/// The working set is the whole test process's, and one test caps it.
static WORKING_SET: std::sync::Mutex<()> = std::sync::Mutex::new(());
#[test]
fn touched_memory_counts_as_resident() {
let _alone = WORKING_SET.lock().unwrap();
const SIZE: usize = 256 << 20;
let before = resident_bytes().unwrap();
let block = vec![1u8; SIZE];
let during = resident_bytes().unwrap();
std::hint::black_box(&block);
assert!(
during >= before + SIZE as u64 / 2,
"{before} then {during} bytes"
);
}
#[test]
fn usage_says_how_tight_a_cap_nothing_enforces_is() {
const GB: u64 = 1 << 30;
assert_eq!(pressure_of_usage(GB / 2, GB), Pressure::Room);
assert_eq!(pressure_of_usage(GB / 10 * 8, GB), Pressure::Steady);
let Pressure::Over { keep } = pressure_of_usage(2 * GB, GB) else {
panic!("twice the cap is over it");
};
assert!((keep - 0.4).abs() < 0.001, "{keep}");
}
#[test]
fn page_faults_say_how_tight_a_cap_the_system_enforces_is() {
assert_eq!(pressure_of_faults(50_000.), Pressure::Room);
assert_eq!(pressure_of_faults(140_000.), Pressure::Steady);
assert!(matches!(
pressure_of_faults(290_000.),
Pressure::Over { .. }
));
}
#[cfg(windows)]
#[test]
fn the_system_holds_the_game_under_a_cap_and_lifting_it_lets_memory_back() {
let _alone = WORKING_SET.lock().unwrap();
const SIZE: usize = 256 << 20;
const CAP: u64 = 128 << 20;
let mut block = vec![1u8; SIZE];
system_cap(Some(CAP));
block.iter_mut().step_by(4096).for_each(|b| *b = 2);
let capped = resident_bytes().unwrap();
assert!(capped <= CAP, "{capped} bytes under a cap of {CAP}");
system_cap(None);
block.iter_mut().step_by(4096).for_each(|b| *b = 3);
let lifted = resident_bytes().unwrap();
std::hint::black_box(&block);
assert!(lifted > CAP, "{lifted} bytes with the cap lifted");
}
#[test]
fn only_drawing_nothing_while_faulting_hard_counts_as_frozen() {
assert!(frozen(STALL, STALL_FAULTS * 10.));
// Slow but drawing, as at 1 frame a second.
assert!(!frozen(Duration::from_secs(1), STALL_FAULTS * 10.));
// Minimized or waiting: no frames, and no memory being fetched back.
assert!(!frozen(STALL * 10, 100.));
}
#[test]
fn only_staying_over_with_nothing_left_to_give_up_ends_the_game() {
let start = Instant::now();
let later = |d: Duration| start + d;
let mut over = Over::default();
assert!(!over.gave_up(start, true, false));
assert!(!over.gave_up(later(GRACE / 2), true, false));
assert!(over.gave_up(later(GRACE), true, false));
// Getting back under the cap starts the count again.
let mut over = Over::default();
assert!(!over.gave_up(start, true, false));
assert!(!over.gave_up(later(GRACE / 2), false, false));
assert!(!over.gave_up(later(GRACE), true, false));
// So does having something left to give up, however long the game is over.
let mut over = Over::default();
assert!(!over.gave_up(start, true, false));
assert!(!over.gave_up(later(GRACE * 5), true, true));
assert!(!over.gave_up(later(GRACE * 6), true, false));
// A cap turned off, then on again, or changed, gets its whole grace again.
let mut over = Over::default();
over.follow(Some(1 << 30));
assert!(!over.gave_up(start, true, false));
over.follow(None);
over.follow(Some(1 << 30));
assert!(!over.gave_up(later(GRACE), true, false));
over.follow(Some(1 << 29));
assert!(!over.gave_up(later(GRACE * 2), true, false));
over.follow(Some(1 << 29));
assert!(over.gave_up(later(GRACE * 3), true, false));
}
#[test]
fn saying_the_game_can_shrink_holds_the_last_resort_off_for_a_while() {
can_shrink();
assert!(since_start() < SHRINKS_UNTIL.load(Ordering::Relaxed));
}
}