Runners send their facts with every claim: free disk, load, speed 62829d15ef09

//! What a runner measures about itself (spec §11.1, docs/jetstream.md §6):

//! free disk, load and the kernel each claim, cheaply; and its speed, from

//! a short fixed benchmark run at start and again while idle.

use crate::home::Home;

use flow_core::api::Facts;

use std::time::Instant;

/// The benchmark's time on the reference machine (Earth), in ms: a runner

/// that takes as long scores 100.

const REFERENCE_MS: f64 = 225.0;

/// The cheap facts, with the last speed measured.

pub fn now(home: &Home, speed: Option<u32>) -> Facts {

    Facts {

        free_disk_mib: free_disk_mib(&home.root),

        load_x100: load_x100(),

        speed,

        speed_class: speed.map(Facts::class_of),

        kernel: std::fs::read_to_string("/proc/sys/kernel/osrelease").ok().map(|s| s.trim().to_string()),

    }

}

/// Free space for an unprivileged writer on the file system holding `path`, in MiB.

pub fn free_disk_mib(path: &std::path::Path) -> Option<u64> {

    use std::os::unix::ffi::OsStrExt;

    let c = std::ffi::CString::new(path.as_os_str().as_bytes()).ok()?;

    let mut s: libc::statvfs = unsafe { std::mem::zeroed() };

    // SAFETY: `c` is a valid NUL-terminated path and `s` a writable statvfs.

    if unsafe { libc::statvfs(c.as_ptr(), &mut s) } != 0 {

        return None;

    }

    Some((s.f_bavail as u64).saturating_mul(s.f_frsize as u64) >> 20)

}

/// The 1-minute load average from /proc/loadavg, times 100.

pub fn load_x100() -> Option<u32> {

    let text = std::fs::read_to_string("/proc/loadavg").ok()?;

    let first: f64 = text.split_whitespace().next()?.parse().ok()?;

    Some((first * 100.0).round() as u32)

}

/// The benchmark, one thread: BLAKE3 over 256 MiB (spec §11.1), and a sort

/// of 4 Mi pseudo-random words for the integer and memory side. Answers

/// the score, 100 on the reference machine, and the time it took.

pub fn bench() -> (u32, u128) {

    let start = Instant::now();

    let buf: Vec<u8> = (0..32u32 << 20).map(|i| (i.wrapping_mul(2_654_435_761) >> 13) as u8).collect();

    let mut h = blake3::Hasher::new();

    for _ in 0..8 {

        h.update(&buf);

    }

    std::hint::black_box(h.finalize());

    drop(buf);

    let mut x: u64 = 0x9e37_79b9_7f4a_7c15;

    let mut words: Vec<u64> = (0..4u64 << 20)

        .map(|_| {

            x ^= x << 13;

            x ^= x >> 7;

            x ^= x << 17;

            x

        })

        .collect();

    words.sort_unstable();

    std::hint::black_box(&words);

    let ms = start.elapsed().as_millis().max(1);

    ((REFERENCE_MS * 100.0 / ms as f64).round() as u32, ms)

}

#[cfg(test)]

mod tests {

    use super::*;

    #[test]

    fn the_cheap_facts_are_read_and_classes_double() {

        assert!(free_disk_mib(std::path::Path::new("/")).is_some());

        assert!(load_x100().is_some());

        assert_eq!(Facts::class_of(100), 3, "the reference machine");

        assert_eq!((Facts::class_of(50), Facts::class_of(200), Facts::class_of(500), Facts::class_of(10)), (2, 4, 5, 1));

    }

}

    /// What the runner measured about itself just now (spec §11.1,

    /// docs/jetstream.md §6). Absent: an older runner.

    #[serde(default, skip_serializing_if = "Option::is_none")]

    pub facts: Option<Facts>,

}

/// A runner's own measurements, sent with every claim (spec §11.1): cheap

/// ones taken each time, the speed from a short benchmark run at start and

/// again while idle. Whole numbers, so a claim compares exactly.

#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]

pub struct Facts {

    /// Free disk where jobs' disks are made, in MiB.

    #[serde(default, skip_serializing_if = "Option::is_none")]

    pub free_disk_mib: Option<u64>,

    /// The 1-minute load average, times 100.

    #[serde(default, skip_serializing_if = "Option::is_none")]

    pub load_x100: Option<u32>,

    /// The benchmark's score: 100 on the reference machine (Earth), twice

    /// as fast scoring 200.

    #[serde(default, skip_serializing_if = "Option::is_none")]

    pub speed: Option<u32>,

    /// The speed class, 1 (slow) to 5 (fast); each class twice the one

    /// below (spec §11.1).

    #[serde(default, skip_serializing_if = "Option::is_none")]

    pub speed_class: Option<u8>,

    /// The kernel release.

    #[serde(default, skip_serializing_if = "Option::is_none")]

    pub kernel: Option<String>,

}

impl Facts {

    /// The class of a speed score: 3 for the reference machine's 100, each

    /// class a factor of two.

    pub fn class_of(speed: u32) -> u8 {

        match speed {

            0..=34 => 1,

            35..=69 => 2,

            70..=139 => 3,

            140..=279 => 4,

            _ => 5,

        }

    }

mod facts;

    /// Measure this machine as a runner does: its speed score (100 on the

    /// reference machine) and class, free disk and load (spec §11.1)

    Bench,

        Cmd::Runner { cmd: Some(RunnerCmd::Bench) } => {

            let home = Home::locate(cli.home.as_deref())?;

            let (speed, ms) = facts::bench();

            let f = facts::now(&home, Some(speed));

            println!("speed {speed} (class {}), benchmark {ms} ms", flow_core::api::Facts::class_of(speed));

            println!("free disk {} MiB at {}", f.free_disk_mib.unwrap_or(0), home.root.display());

            println!("load {:.2}", f.load_x100.unwrap_or(0) as f64 / 100.0);

            if let Some(k) = f.kernel {

                println!("kernel {k}");

            }

            Ok(())

        }

        // The speed (spec §11.1): measured now, and again every 15 minutes

        // while no job runs, so a job never shares the CPU with it.

        let measure = || {

            let (speed, ms) = crate::facts::bench();

            eprintln!("flow runner {name}: speed {speed} (class {}), benchmark {ms} ms", flow_core::api::Facts::class_of(speed));

            speed

        };

        let mut speed = measure();

        let mut benched = Instant::now();

            if used.lock().unwrap().jobs == 0 && benched.elapsed() >= Duration::from_secs(15 * 60) {

                speed = measure();

                benched = Instant::now();

            }

                facts: Some(crate::facts::now(home, Some(speed))),

| `speed` | A score and a class from 1 (slow) to 5 (fast), measured by the runner at start, again every 15 minutes while it runs no job, and by `flow runner bench`: a fixed one-thread workload (BLAKE3 over 256 MiB, and a sort of 4 Mi words, where a C compiler cannot be assumed) whose time on the reference machine (Earth, about 225 ms) scores 100; class 3 is 70–139, each class a factor of two (done 2026-10-11, `facts` on the claim) |

| `load` | The 1-minute load average (×100), and the free disk where jobs' disks are made, sent with every claim (`facts`); memory free and jobs running as before |