Enum CpusetSpec 

#[non_exhaustive]
pub enum CpusetSpec {
    Llc(usize),
    Numa(usize),
    Range {
        start_frac: f64,
        end_frac: f64,
    },
    Disjoint {
        index: usize,
        of: usize,
    },
    Overlap {
        index: usize,
        of: usize,
        frac: f64,
    },
    Exact(BTreeSet<usize>),
}

How to compute a cpuset from topology.

#[non_exhaustive]

CpusetSpec is #[non_exhaustive] — see [crate::non_exhaustive] for the cross-crate pattern-match and construction rules shared by every such type.

Variant-specific guidance for CpusetSpec: prefer the associated constructor functions — Self::llc, Self::numa, Self::range, Self::disjoint, Self::overlap, and Self::exact — over naming variant literals like CpusetSpec::Llc(0) or CpusetSpec::Range { start_frac, end_frac }. Two reasons:

1. Stability across variant reshaping. A future commit that adds a field to Range (e.g. a stride parameter) breaks every caller that spelled out CpusetSpec::Range { start_frac, end_frac }; the Self::range(..) constructor absorbs the new field behind a defaulted parameter. The #[non_exhaustive] attribute is what reserves that freedom for the enum; the constructor convention is how callers opt into benefiting from it.
2. Semantic consistency with Self::exact. The exact constructor accepts any IntoIterator<Item = usize> (arrays, ranges, Vec, BTreeSet) and converts to BTreeSet<usize> internally; callers that bypass it and write CpusetSpec::Exact(set) directly must hand-build the BTreeSet — duplicate bookkeeping a future-proofed constructor erases.

Test code that needs to inspect a variant via pattern match necessarily references the variant literal (the name is load- bearing for the match), so the construction-side rule is a convention for production call sites, not a hard constraint. Inside this crate, matchers obey the pattern-side rule above; constructors obey this rule.

Clone + Debug + PartialEq. Eq / Hash are impossible because Range and Overlap carry f64 fractions; Default has no honest value (Llc(0) vs. Range(0..1) vs. Exact(empty) are all different “no-op” semantics).

Note: f64::NAN != f64::NAN per IEEE 754, so a CpusetSpec containing NaN fractions will not equal a clone of itself; validate() rejects NaN inputs.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Llc(usize)

All CPUs in a given LLC index.

Numa(usize)

All CPUs in a given NUMA node index.

Range

Fractional range of usable CPUs [start_frac..end_frac).

Fields

start_frac: f64

end_frac: f64

Disjoint

Partition usable CPUs into of equal disjoint sets; take the index-th.

Fields

index: usize

of: usize

Overlap

Like Disjoint but each set overlaps neighbors by frac of its size.

Fields

index: usize

of: usize

frac: f64

Exact(BTreeSet<usize>)

Exact CPU set (no topology resolution).

Implementations

impl CpusetSpec

pub fn exact(cpus: impl IntoIterator<Item = usize>) -> Self

Construct an Exact cpuset from any iterator of CPU indices.

Accepts arrays, ranges, Vec, BTreeSet, or any IntoIterator<Item = usize>.

pub const fn disjoint(index: usize, of: usize) -> Self

Partition usable CPUs into of equal disjoint sets; take the index-th.

pub const fn overlap(index: usize, of: usize, frac: f64) -> Self

Like disjoint but each set overlaps neighbors by frac of its size.

pub const fn range(start_frac: f64, end_frac: f64) -> Self

Fractional range of usable CPUs [start_frac..end_frac).

pub const fn llc(index: usize) -> Self

All CPUs in a given LLC index.

pub const fn numa(index: usize) -> Self

All CPUs in a given NUMA node index.

impl CpusetSpec

pub fn validate(&self, ctx: &Ctx<'_>) -> Result<(), String>

Check whether this spec can produce a non-empty cpuset for the given topology. Returns Err with a human-readable reason on failure.

pub fn resolve(&self, ctx: &Ctx<'_>) -> BTreeSet<usize>

Resolve to a concrete CPU set given the topology.

Callers SHOULD run Self::validate first and propagate its error. apply_setup and apply_ops::SetCpuset do so via anyhow::bail!, then call Self::resolve_quiet which skips the warns this method emits on degenerate inputs.

Defense-in-depth: every malformed input that validate rejects (out-of-range Llc/Numa, partition of == 0, index >= of, inverted or non-finite Range.start_frac / end_frac, out-of-bounds Overlap.frac) also has a panic-free fallback here — out-of-range indices clamp to the last valid index with a tracing::warn!, of == 0 returns an empty set with a warn, and inverted/non-finite fracs clamp to [0, len] so the resulting slice never inverts. Skipping validate therefore degrades into a usable (possibly empty) cpuset rather than crashing the caller, but the warns surface the silent-degradation case — a caller who computed a CPU count via crate::scenario::Ctx::cpuset_cpus (which doesn’t validate) sees the warn instead of silently planning against the wrong denominator.

pub fn resolve_quiet(&self, ctx: &Ctx<'_>) -> BTreeSet<usize>

Like Self::resolve but suppresses the degenerate-input tracing::warn!s. Use this from call sites that pair the resolution with a Self::validate call (either before or after this one) and bail on its error — validate is the canonical error channel for malformed specs, and a warn here would be redundant noise on a path already known- broken via the validate gate. apply_setup resolves first (to keep the workers_pct empty-cpuset diagnostic ahead of validate’s generic empty-Exact rejection) and validates after; Op::SetCpuset validates first and resolves after. Both patterns satisfy the contract.

Trait Implementations

impl Clone for CpusetSpec

fn clone(&self) -> CpusetSpec

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for CpusetSpec

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

Formats the value using the given formatter.

impl PartialEq for CpusetSpec

fn eq(&self, other: &CpusetSpec) -> 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 StructuralPartialEq for CpusetSpec