runnerd-core 0.0.29

Config, domain logic and API types shared by runnerd and its clients
Documentation
//! What the host's memory leaves runners beside its other programs (ADR 0055): the slice's runners may hold what
//! they hold now without page cache plus the host's `MemAvailable`, less a margin kept for the host's page cache, so
//! reclaim stays cheap; and nothing starts while the host, short of memory, stalls for it. The stall bound has
//! hysteresis, and the margin grows by half only while no waiter fits the plain one (ADR 0102), so a host at the edge
//! does not start and hold runners by turns. A host whose memory can grow to a
//! ceiling, `[host] memory_ceiling` (ADR 0084), counts what it can still grow by as available and keeps the margin of
//! its ceiling; the stall rule reads the memory the host has now. Pure: the engine passes in the reading, with the ceiling,
//! and what it remembers of the last plan.

use super::pooled;
use crate::api::{HostBudget, HostMemory, host_margin};

/// Starts stop once every runnable task of the host waits for memory this share of the last 10 s, in hundredths of
/// a percent: 5%, while the host is short of memory (`stalls`).
pub const STALL_ENTER: u32 = 500;

/// Once stopped, starts resume when that share falls under this: 1%.
pub const STALL_LEAVE: u32 = 100;

/// What admission remembers of the host from the last plan.
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
pub struct Remembered {
    /// The host stalled, or jobs waited for its memory and none fitted even the plain margin (`short`): the margin
    /// grows by half. The engine clears it while no runner runs, so the first runner into an empty slice needs only the
    /// margin.
    pub short: bool,
    /// The host stalled: starts resume only under `STALL_LEAVE`.
    pub stalled: bool,
}

/// The margin `MemAvailable` keeps beside the runners' predicted peaks for a host with `total` memory: `host_margin`,
/// half again as much while the host is `short`.
pub fn margin(total: u64, short: bool) -> u64 {
    let margin = host_margin(total);
    if short {
        margin.saturating_add(margin / 2)
    } else {
        margin
    }
}

/// Whether the larger margin stands for the next plan, by what `memory` leaves beside the `reserved` memory of what runs
/// and the memory each job waiting for the host `needs` (ADR 0102): while the host stalls, or while jobs wait and none
/// fits the plain margin. One that does fits at the next plan, so a queue does not hold the margin up by waiting in it.
/// A deficit stays negative here, so it never reads as a fit.
pub fn short(
    memory: &HostMemory,
    reserved: u64,
    stalled: bool,
    needs: impl IntoIterator<Item = u64>,
) -> bool {
    if stalled {
        return true;
    }
    let room = left(limit(memory, false), reserved, false);
    let mut needs = needs.into_iter().peekable();
    needs.peek().is_some()
        && needs.all(|needs| i64::try_from(needs).ok().is_none_or(|needs| needs > room))
}

/// What the host keeps past the margin before a credit stands, as a divisor of its memory: a quarter. A credit lets the
/// slice fill past what the plain count allows, so none stands near where sockets start to throttle, under about 20G of
/// 62G available, which the margin and this come to (ADR 0099).
const CREDIT_ALLOWANCE_SHARE: u64 = 4;

/// The host as the pooled count reads it, by the margin in force.
pub fn pooling(memory: &HostMemory, remembered: Remembered) -> pooled::Host {
    let stalled = stalls(memory, remembered.stalled);
    let margin = margin(memory.grown(), remembered.short || stalled);
    pooled::Host {
        available: memory.available.saturating_add(memory.growable()),
        keeps: margin.saturating_add(memory.grown() / CREDIT_ALLOWANCE_SHARE),
        stalled,
    }
}

/// Whether `memory`'s stall shares say the host stalls for memory, given whether it did at the last plan. A stall
/// counts only while `MemAvailable` is under twice the margin: the shares are the whole host's, and a runner
/// reclaiming at its own cap raises them with memory to spare, which starts elsewhere do not make worse. A ceiling
/// changes nothing here (ADR 0084): what the host could still grow by is not available, and a stall while it is
/// short says the hypervisor is not giving it.
pub fn stalls(memory: &HostMemory, before: bool) -> bool {
    let full = memory.full.map_or(0, |full| full.avg10);
    let stalling = full >= STALL_ENTER || (before && full >= STALL_LEAVE);
    stalling && memory.available < margin(memory.total, false).saturating_mul(2)
}

/// What `memory` lets the slice's runners hold in all: what the slice holds now without page cache plus
/// `MemAvailable` and what the host can still grow by (`HostMemory::growable`), less the margin of the host's memory
/// at its ceiling, larger while the host is `short`. Without a ceiling above `MemTotal`, the slice and
/// `MemAvailable` less the margin of `MemTotal`.
pub fn limit(memory: &HostMemory, short: bool) -> u64 {
    memory
        .slice
        .saturating_add(memory.available)
        .saturating_add(memory.growable())
        .saturating_sub(margin(memory.grown(), short))
}

/// What `memory` leaves runners beside the `reserved` memory of what runs in the slice, given what the last plan
/// `remembered`.
pub fn budget(memory: HostMemory, reserved: u64, remembered: Remembered) -> HostBudget {
    let stalled = stalls(&memory, remembered.stalled);
    let limit = limit(&memory, remembered.short || stalled);
    HostBudget {
        memory,
        limit,
        spare: u64::try_from(left(limit, reserved, stalled)).unwrap_or(0),
        stalled,
    }
}

/// What a host `limit` leaves new runners beside the `reserved` memory of what runs in the slice: negative by what
/// they reserve past it, none while the host is `stalled`. A runner that stops gives its reservation back to this,
/// so a deficit stays owed rather than hidden by `HostBudget::spare`, which stops at 0.
pub fn left(limit: u64, reserved: u64, stalled: bool) -> i64 {
    if stalled {
        return 0;
    }
    let bytes = |bytes: u64| i64::try_from(bytes).unwrap_or(i64::MAX);
    bytes(limit).saturating_sub(bytes(reserved))
}

/// What `memory` leaves a new runner beside the `reserved` memory of what runs or is reserved for before it starts,
/// such as the mirror: `budget`'s `spare` with no wait or stall remembered and none now. Beside only the mirror's
/// cap, the room of the first runner into an empty slice, which `runnerd init` sizes a starter runner within and
/// `runnerd doctor` checks profiles against.
pub fn first_runner(memory: &HostMemory, reserved: u64) -> u64 {
    u64::try_from(left(limit(memory, false), reserved, false)).unwrap_or(0)
}

#[cfg(test)]
mod tests;