Struct CpuCap 

pub struct CpuCap { /* private fields */ }

Re-export of the internal vmm::host_topology::CpuCap type so the ktstr and cargo-ktstr CLI binaries (which import this module through the pub mod cli surface) can resolve --cpu-cap N without depending on the pub(crate) vmm module. Keeping the canonical definition in vmm::host_topology (so the acquire_llc_plan internal call site consumes its own type without needing cli) and re-exporting here — versus inverting the dependency — avoids pulling the CLI module into the VMM internals. Parsed --cpu-cap N value. N is a CPU count: the planner reserves exactly N host CPUs by walking whole LLCs in contention- / NUMA-aware order (filtered to the calling process’s allowed cpuset) and partial-taking the last LLC so plan.cpus.len() == N. The flock set is still per-LLC (the last LLC is flocked whole even when only a prefix of its CPUs enters plan.cpus). Bounded to 1..=usize::MAX at the constructor — a cap of 0 is nonsensical (reserving zero CPUs is just “don’t run”) and rejected upstream by the CLI layer, but we enforce the bound in the type system via NonZeroUsize so callers can CpuCap::new(...)? without a follow-up bounds check.

The runtime upper bound — “don’t exceed the process’s allowed CPU count” — is enforced at acquire time via CpuCap::effective_count because the allowed set is not known until host_allowed_cpus reads sched_getaffinity.

Implementations

impl CpuCap

pub fn new(n: usize) -> Result<Self>

Construct from a raw usize CPU count. Returns Err on 0; usize::MAX is accepted here and clamped later by effective_count.

pub fn resolve(cli_flag: Option<usize>) -> Result<Option<CpuCap>>

Three-tier resolution: explicit CLI flag wins over env var, which wins over “not set”. Returns None when neither is present, meaning “use the caller’s auto-sized default”: the kernel-build/planner path expands None to default_cpu_budget (30% of the allowed set); the no-perf VM-builder path expands it to no_perf_cpu_budget (max(30%, min(vcpus, allowed)), usually the vCPU count).

Env var is KTSTR_CPU_CAP (integer ≥ 1, CPU count). An empty or unset env var is treated as absent; a non-numeric value OR the numeric value 0 is an error — KTSTR_CPU_CAP=0 flows through CpuCap::new(0) which rejects with “–cpu-cap must be ≥ 1 CPU (got 0)”. Zero is not a silent fallback to “no cap”; it surfaces as a parse-time error so typos and scripting mistakes don’t accidentally disable the resource contract.

pub fn effective_count(&self, allowed_cpus: usize) -> Result<usize>

Runtime-bounded cap: returns the inner count unless it exceeds allowed_cpus (the calling process’s sched_getaffinity cpuset count), in which case a CpuBudgetUnsatisfiable hard error (an explicit cap the host cannot satisfy is a FAIL, not a transient skip) steers the caller toward an actionable message. This check lives at acquire time — not at construction — because the allowed set is not known until host_allowed_cpus reads the syscall.

Trait Implementations

impl Clone for CpuCap

fn clone(&self) -> CpuCap

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for CpuCap

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for CpuCap

fn eq(&self, other: &CpuCap) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for CpuCap

impl Eq for CpuCap

impl StructuralPartialEq for CpuCap