Skip to main content

Module scheduling

Module scheduling 

Source
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§

CandidateOutcome
One candidate’s verdict in a SelectionReport (generic — consumer-agnostic; selection.rs adds its own backend-specific fields when it adopts this).
LabelSelector
One label-selector conjunct: key <op> values. A query carries a list of these (all must match — AND). values is ignored for Exists/DoesNotExist.
Outcome
Per-candidate outcome from filter: the candidate plus its first rejection (if any). Short-circuits per candidate on the first rejecting predicate.
PlacementCandidate
A placement candidate returned by queryCandidates.
PlacementCandidateSet
Bounded result set. total_matching is the full match count before the bound was applied.
RejectionReason
Why a predicate rejected a candidate (carried into the explain trace).
Resource
A named resource amount ({name, quantity}); quantity is a k8s-quantity string e.g. "8", "512Gi", "100m".
ResourceRequest
A resource requirement: a candidate must have at least min_quantity of name allocatable (declared − already-allocated).
SelectionReport
Full trace of a selection decision: every candidate considered + the winner. The explain shape (generalized from the backend-selection diagnostics).

Enums§

SelectorOp
Label-selector match operator (k8s match-expressions).

Traits§

CapabilitySource
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 claiming runtime=kata and the live selection.rs knowing cloud-hypervisor is 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 (typically filter(...).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. identify maps a &C to the name used in the report’s per-candidate entries (so the report stays generic over C).

Type Aliases§

Predicate
A predicate over a candidate: returns None if it passes, Some(reason) if rejected (and why). Because every predicate returns its reason, a SelectionReport trace falls out of filter / select for free.