Expand description
#523 P0 / #524 / #628 — Scheduling Substrate.
The shared LabelSelector / ResourceRequest / PlacementCandidate
vocabulary + a small filter → rank → select helper + one SelectionReport
explain shape + a CapabilitySource contract, so every scheduling surface
(placement queryCandidates, the SandboxPool engine, CellRouter routing,
backend selection.rs) composes without duplicating filter/rank/explain
logic or capability truth.
Not a framework: free functions + plain types. See the module doc. Scheduling Substrate — the shared vocabulary + small primitives every scheduling surface composes on (#523 P0 / #524 / #628).
Five selection systems grew independently (selection.rs backend pick,
SandboxPool::acquire, DevicePool, CellRouter/HRW routing,
queryCandidates). They share one shape —
candidates → filter(predicates) → rank → select → explain — so this module
is the ONE place that shape lives. Each provider declares capability truth
once (as labels + resources via [CapabilitySource]); each consumer filters
and ranks through [filter] / [rank] / [select] and gets a trace
([SelectionReport]) for free, because every [Predicate] returns why it
rejected.
§Guardrail (non-negotiable)
This is small on purpose: plain types + free functions. No trait towers,
no Scheduler<T> abstraction-without-consumers. If it grows past
“vocabulary + small helpers,” it is wrong — extend by adding real consumers,
not by abstracting in a vacuum.
Structs§
- Candidate
Outcome - One candidate’s verdict in a
SelectionReport(generic — consumer-agnostic;selection.rsadds its own backend-specific fields when it adopts this). - Label
Selector - One label-selector conjunct:
key <op> values. A query carries a list of these (all must match — AND).valuesis ignored forExists/DoesNotExist. - Outcome
- Per-candidate outcome from
filter: the candidate plus its first rejection (if any). Short-circuits per candidate on the first rejecting predicate. - Placement
Candidate - A placement candidate returned by
queryCandidates. - Placement
Candidate Set - Bounded result set.
total_matchingis the full match count before the bound was applied. - Rejection
Reason - Why a predicate rejected a candidate (carried into the explain trace).
- Resource
- A named resource amount (
{name, quantity});quantityis a k8s-quantity string e.g."8","512Gi","100m". - Resource
Request - A resource requirement: a candidate must have at least
min_quantityofnameallocatable (declared − already-allocated). - Selection
Report - Full trace of a selection decision: every candidate considered + the winner. The explain shape (generalized from the backend-selection diagnostics).
Enums§
- Selector
Op - Label-selector match operator (k8s match-expressions).
Traits§
- Capability
Source - A provider of scheduling capability truth: emits its stable capabilities +
declared capacity in the shared vocabulary so a
PlacementCandidate/ node record can aggregate them (one source of truth — no hand-declaration, no drift between e.g. a node record claimingruntime=kataand the liveselection.rsknowingcloud-hypervisoris missing).
Functions§
- filter
- Run every candidate through every predicate, recording the first rejection (if any) per candidate. Predicates are evaluated in order; a candidate rejected by predicate i is not tested against i+1.
- parse_
k8s_ quantity - Parse a k8s-quantity string into a canonical comparable value (milli of the
base unit, as
i128). Handles the common suffixes: - rank
- Order survivors by
by. Stable. Consumes the slice of survivor references (typicallyfilter(...).iter().filter(|o| o.passed()).map(|o| o.candidate)). - select
- The full pipeline: filter → rank → bounded select, returning both the chosen
candidates and the explain trace.
identifymaps a&Cto the name used in the report’s per-candidate entries (so the report stays generic overC).
Type Aliases§
- Predicate
- A predicate over a candidate: returns
Noneif it passes,Some(reason)if rejected (and why). Because every predicate returns its reason, aSelectionReporttrace falls out offilter/selectfor free.