wowlab_common/sys/

mod.rs

// #t(file: rust_forbidden_deps) System-level helper, never compiled for WASM.
// #t(file: rust_ffi_crate_naming) Private platform adapter owns the narrow sysctl FFI boundary.

//! Platform-specific system information: CPU, memory, load averages.

use wowlab_types::{
    constants::{BYTES_PER_MB, HUNDRED},
    sim::FastSet,
};

const LOAD_AVG_COUNT: usize = 3;

/// CPU tick snapshot used to derive usage across a sampling interval.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct CpuTicks {
    total: u64,
    idle: u64,
}

impl CpuTicks {
    /// Construct a snapshot from cumulative total and idle tick counters.
    #[must_use]
    pub const fn new(total: u64, idle: u64) -> Self {
        Self { total, idle }
    }

    /// Return the cumulative total tick counter.
    #[must_use]
    pub const fn total(self) -> u64 {
        self.total
    }

    /// Return the cumulative idle tick counter.
    #[must_use]
    pub const fn idle(self) -> u64 {
        self.idle
    }
}

/// Compute CPU usage percentage from two tick snapshots.
#[must_use]
pub fn cpu_usage_from_ticks(before: CpuTicks, after: CpuTicks) -> f64 {
    let total_delta = after.total.saturating_sub(before.total);

    if total_delta == 0 {
        return 0.0;
    }

    let idle_delta = after.idle.saturating_sub(before.idle);
    let active_delta = total_delta.saturating_sub(idle_delta);

    HUNDRED * wowlab_types::numeric::u64_to_f64(active_delta)
        / wowlab_types::numeric::u64_to_f64(total_delta)
}

/// Total number of logical CPU cores.
#[must_use]
pub fn logical_cores() -> usize {
    std::thread::available_parallelism().map_or(1, std::num::NonZero::get)
}

/// Optimal core count for compute work: P-cores on Apple Silicon, physical on x86.
#[must_use]
pub fn optimal_concurrency() -> usize {
    #[cfg(target_arch = "aarch64")]
    {
        aarch64_performance_cores().unwrap_or_else(physical_cores)
    }

    #[cfg(target_arch = "x86_64")]
    {
        physical_cores()
    }

    #[cfg(not(any(target_arch = "aarch64", target_arch = "x86_64")))]
    {
        logical_cores()
    }
}

/// Physical CPU core count (best-effort, falls back to logical).
#[must_use]
pub fn physical_cores() -> usize {
    #[cfg(target_os = "macos")]
    {
        let n = sysctl_usize("hw.physicalcpu");

        if n > 0 { n } else { logical_cores() }
    }

    #[cfg(target_os = "linux")]
    {
        let Ok(cpuinfo) = wowlab_fs::file::read_text(wowlab_fs::path::Path::new("/proc/cpuinfo"))
        else {
            return logical_cores();
        };
        let mut ids = FastSet::default();

        for line in cpuinfo.lines() {
            if line.starts_with("core id") {
                if let Some(id) = line
                    .split(':')
                    .nth(1)
                    .and_then(|v| v.trim().parse::<u32>().ok())
                {
                    ids.insert(id);
                }
            }
        }

        if ids.is_empty() {
            logical_cores()
        } else {
            ids.len()
        }
    }

    #[cfg(not(any(target_os = "macos", target_os = "linux")))]
    {
        logical_cores()
    }
}

#[cfg(target_arch = "aarch64")]
fn aarch64_performance_cores() -> Option<usize> {
    #[cfg(target_os = "macos")]
    {
        macos_perflevel_cores(0)
    }

    #[cfg(target_os = "linux")]
    {
        linux_big_cores()
    }

    #[cfg(not(any(target_os = "macos", target_os = "linux")))]
    {
        None
    }
}

#[cfg(all(target_arch = "aarch64", target_os = "macos"))]
fn macos_perflevel_cores(level: u32) -> Option<usize> {
    use std::{
        ffi::CString,
        mem::MaybeUninit,
        os::raw::{c_int, c_void},
    };

    extern "C" {
        fn sysctlbyname(
            name: *const i8,
            oldp: *mut c_void,
            oldlenp: *mut usize,
            newp: *mut c_void,
            newlen: usize,
        ) -> c_int;
    }

    let name = CString::new(format!("hw.perflevel{level}.logicalcpu")).ok()?;
    let mut value = MaybeUninit::<i32>::uninit();
    let mut size = std::mem::size_of::<i32>();

    // SAFETY: valid CString name and correctly sized output buffer.
    let result = unsafe {
        sysctlbyname(
            name.as_ptr(),
            value.as_mut_ptr().cast(),
            &mut size,
            std::ptr::null_mut(),
            0,
        )
    };

    if result == 0 && size == std::mem::size_of::<i32>() {
        // SAFETY: sysctlbyname returned 0 (success) and wrote exactly size_of::<i32>() bytes.
        let cores = unsafe { value.assume_init() };

        if cores > 0 {
            return Some(cores as usize);
        }
    }

    None
}

#[cfg(all(target_arch = "aarch64", target_os = "linux"))]
const BIG_CORE_CAPACITY_THRESHOLD: u32 = 900;

#[cfg(all(target_arch = "aarch64", target_os = "linux"))]
fn linux_big_cores() -> Option<usize> {
    use wowlab_fs::{directory, file, path::Path};

    let cpu_base = Path::new("/sys/devices/system/cpu");

    if directory::inspect(&cpu_base.join("cpu0/cpu_capacity"))
        .ok()?
        .is_none()
    {
        return None;
    }

    let mut big_cores = 0;
    let mut found_any = false;

    for entry in directory::entries(cpu_base).ok()? {
        let name = entry.path().file_name()?;
        let name_str = name.to_string_lossy();

        if !name_str.starts_with("cpu") {
            continue;
        }

        if name_str
            .strip_prefix("cpu")
            .and_then(|s| s.parse::<u32>().ok())
            .is_none()
        {
            continue;
        }

        let capacity_path = entry.path().join("cpu_capacity");

        if let Ok(content) = file::read_text(&capacity_path) {
            if let Ok(capacity) = content.trim().parse::<u32>() {
                found_any = true;

                if capacity >= BIG_CORE_CAPACITY_THRESHOLD {
                    big_cores += 1;
                }
            }
        }
    }

    if found_any && big_cores > 0 {
        Some(big_cores)
    } else {
        None
    }
}

#[cfg(target_os = "linux")]
#[path = "linux.rs"]
mod inner;

#[cfg(target_os = "macos")]
#[path = "macos.rs"]
mod inner;

#[cfg(target_os = "windows")]
#[path = "windows.rs"]
mod inner;

#[cfg(not(any(target_os = "linux", target_os = "macos", target_os = "windows")))]
#[path = "fallback.rs"]
mod inner;

pub use inner::{cpu_model, read_cpu_ticks, read_load_average, read_memory_mb, read_os_memory_mb};

/// Performance core count (P-cores on Apple Silicon, physical on x86).
#[must_use]
pub fn performance_cores() -> usize {
    optimal_concurrency()
}

/// Efficiency core count (E-cores on Apple Silicon, 0 on x86).
#[must_use]
pub fn efficiency_cores() -> usize {
    #[cfg(all(target_arch = "aarch64", target_os = "macos"))]
    {
        macos_perflevel_cores(1).unwrap_or(0)
    }

    #[cfg(all(target_arch = "aarch64", target_os = "linux"))]
    {
        let big = optimal_concurrency();
        let total = physical_cores();

        total.saturating_sub(big)
    }

    #[cfg(not(target_arch = "aarch64"))]
    {
        0
    }
}

/// Snapshot of the host machine's hardware and OS environment.
#[derive(Clone, Debug, serde::Deserialize, serde::Serialize)]
pub struct OsProfile {
    pub cpu_model: String,
    pub logical_cores: usize,
    pub physical_cores: usize,
    pub optimal_cores: usize,
    pub p_cores: usize,
    pub e_cores: usize,
    pub total_memory_mb: u64,
    pub available_memory_mb: u64,
    pub os: String,
    pub arch: String,
}

/// Capture a snapshot of the current host machine profile.
#[must_use]
pub fn os_profile() -> OsProfile {
    let (total_mem, avail_mem) = read_os_memory_mb();

    OsProfile {
        cpu_model: cpu_model(),
        logical_cores: logical_cores(),
        physical_cores: physical_cores(),
        optimal_cores: optimal_concurrency(),
        p_cores: performance_cores(),
        e_cores: efficiency_cores(),
        total_memory_mb: wowlab_types::numeric::f64_to_u64_saturating_trunc(total_mem),
        available_memory_mb: wowlab_types::numeric::f64_to_u64_saturating_trunc(avail_mem),
        os: std::env::consts::OS.to_string(),
        arch: std::env::consts::ARCH.to_string(),
    }
}

#[cfg(target_os = "macos")]
fn sysctl_string(name: &str) -> String {
    use std::ffi::CString;

    let Ok(cname) = CString::new(name) else {
        return String::new();
    };

    let mut size: usize = 0;
    // SAFETY: valid CString name, null output to query size.
    let ret = unsafe {
        libc::sysctlbyname(
            cname.as_ptr(),
            std::ptr::null_mut(),
            &mut size,
            std::ptr::null_mut(),
            0,
        )
    };

    if ret != 0 || size == 0 {
        return String::new();
    }

    let mut buf = vec![0u8; size];
    // SAFETY: correctly sized buffer for sysctlbyname output.
    let ret = unsafe {
        libc::sysctlbyname(
            cname.as_ptr(),
            buf.as_mut_ptr().cast(),
            &mut size,
            std::ptr::null_mut(),
            0,
        )
    };

    if ret != 0 {
        return String::new();
    }

    if buf.last() == Some(&0) {
        buf.pop();
    }

    String::from_utf8_lossy(&buf).trim().to_string()
}

#[cfg(target_os = "macos")]
fn sysctl_usize(name: &str) -> usize {
    use std::ffi::CString;

    let Ok(cname) = CString::new(name) else {
        return 0;
    };

    let mut value: usize = 0;
    let mut size = std::mem::size_of::<usize>();
    // SAFETY: valid CString name and correctly sized output buffer.
    let ret = unsafe {
        libc::sysctlbyname(
            cname.as_ptr(),
            &mut value as *mut _ as *mut libc::c_void,
            &mut size,
            std::ptr::null_mut(),
            0,
        )
    };

    if ret == 0 { value } else { 0 }
}

#[cfg(test)]
mod tests {
    use googletest::prelude::*;
    use rstest::rstest;

    use super::*;

    #[gtest]
    #[rstest]
    #[case::zero_total_delta(CpuTicks::new(0, 0), CpuTicks::new(0, 0), 0.0)]
    #[case::fully_active(CpuTicks::new(0, 0), CpuTicks::new(100, 0), 100.0)]
    #[case::fully_idle(CpuTicks::new(0, 0), CpuTicks::new(100, 100), 0.0)]
    #[case::half_active(CpuTicks::new(0, 0), CpuTicks::new(100, 50), 50.0)]
    #[case::quarter_active_nonzero_base(CpuTicks::new(100, 50), CpuTicks::new(300, 100), 75.0)]
    #[case::after_before_saturates_total(CpuTicks::new(100, 50), CpuTicks::new(50, 20), 0.0)]
    #[case::idle_gt_total_saturates_active(CpuTicks::new(0, 0), CpuTicks::new(100, 200), 0.0)]
    fn cpu_usage_cases(
        #[case] before: CpuTicks,
        #[case] after: CpuTicks,
        #[case] expected: f64,
    ) -> Result<()> {
        verify_that!(cpu_usage_from_ticks(before, after), near(expected, 1e-9))
    }

    #[gtest]
    fn logical_cores_positive() -> Result<()> {
        verify_that!(logical_cores(), gt(0))
    }

    #[gtest]
    fn optimal_le_logical() -> Result<()> {
        verify_that!(optimal_concurrency(), le(logical_cores()))
    }

    #[gtest]
    fn physical_cores_positive() -> Result<()> {
        verify_that!(physical_cores(), gt(0))
    }

    #[gtest]
    fn load_average_non_negative() -> Result<()> {
        let avg = read_load_average();

        for v in avg {
            verify_that!(v, ge(0.0))?;
        }

        Ok(())
    }

    #[gtest]
    fn memory_mb_non_negative() -> Result<()> {
        verify_that!(read_memory_mb(), ge(0.0))
    }

    #[gtest]
    fn os_memory_non_negative() -> Result<()> {
        let (total, available) = read_os_memory_mb();

        verify_that!(total, ge(0.0))?;

        verify_that!(available, ge(0.0))
    }

    #[gtest]
    fn cpu_ticks_some() -> Result<()> {
        if cfg!(any(
            target_os = "linux",
            target_os = "macos",
            target_os = "windows"
        )) {
            verify_that!(read_cpu_ticks(), some(anything()))?;
        }

        Ok(())
    }
}