Crate scx_mlfq 

scx_mlfq, a Multilevel Feedback Queue scheduler for sched_ext.

Per-CPU, virtual-time-ordered user DSQs (Q1/Q2/Q3 per CPU) over an EEVDF virtual-time substrate. Tasks are classified into queues by a regression tree that predicts the next CPU burst from per-task features (see mlfq_tree.rs), with the EMA interactivity gauge as a tree feature and the fallback before the first model. The wakeup path is promotion-only, through the tree, the short-sleep and I/O boost and the band hysteresis. Demotion flows through the run-out gate. See README.md for the design overview.

Re-exports

pub(crate) use std::collections::HashMap; 🔒

pub(crate) use std::collections::HashSet; 🔒

pub(crate) use std::collections::VecDeque; 🔒

pub(crate) use std::mem::MaybeUninit; 🔒

pub(crate) use std::mem::size_of; 🔒

pub(crate) use std::os::fd::AsFd; 🔒

pub(crate) use std::os::fd::AsRawFd; 🔒

pub(crate) use std::sync::Arc; 🔒

pub(crate) use std::sync::atomic::AtomicBool; 🔒

pub(crate) use std::sync::atomic::Ordering; 🔒

pub(crate) use std::time::Duration; 🔒

pub(crate) use anyhow::Result; 🔒

pub(crate) use clap::CommandFactory; 🔒

pub(crate) use clap::Parser; 🔒

pub(crate) use clap_complete::Shell; 🔒

pub(crate) use clap_complete::generate; 🔒

pub(crate) use crossbeam::channel::RecvTimeoutError; 🔒

pub(crate) use libbpf_rs::AsRawLibbpf; 🔒

pub(crate) use libbpf_rs::MapCore; 🔒

pub(crate) use log::info; 🔒

pub(crate) use scx_utils::UserExitInfo; 🔒

pub(crate) use scx_utils::build_id; 🔒

pub(crate) use scx_utils::compat; 🔒

pub(crate) use scx_utils::libbpf_clap_opts::LibbpfOpts; 🔒

pub(crate) use scx_utils::pm; 🔒

pub(crate) use scx_utils::scx_ops_attach; 🔒

pub(crate) use scx_utils::scx_ops_load; 🔒

pub(crate) use scx_utils::scx_ops_open; 🔒

pub(crate) use scx_utils::try_set_rlimit_infinity; 🔒

pub(crate) use scx_utils::uei_exited; 🔒

pub(crate) use scx_utils::uei_report; 🔒

pub use bpf_intf::*;

pub(crate) use scx_stats::prelude::*; 🔒

Modules

alloc 🔒

bpf_intf

bpf_skel 🔒

config 🔒

Userspace configuration, validated scheduling constants written into BPF rodata.

imp

mlfq_tree 🔒

CART regression tree for next-CPU-burst prediction.

stats 🔒

Stats server, #[derive(Stats)] metrics and monitor loop.

topology 🔒

Hybrid-capacity and cache-domain topology discovery.

types

webui 🔒

Loopback web UI: live scheduler metrics as a small HTTP server.

Structs

BpfLinks

BpfMaps

BpfProgs

BpfSkel

BpfSkelBuilder

Config 🔒

Validated scheduling constants.

FitScratch 🔒

Scratch buffers for the CART fit, sized to the maximum window and node budget. The buffers are allocated once with the capacities below and reused across fits by clearing in place, so the training path does not allocate after the first fit. The queue holds owned sample vectors per node; those vectors are still allocated per node, but the major buffers (weights, sorted, left/right) are reused. This keeps the 60s training free of steady-state allocations while preserving the exact CART logic.

Metrics 🔒

ModelMeta 🔒

Metadata of the committed MLFQ tree model, reported to the stats server and the exit log. Defaults describe the untrained state.

OpenBpfMaps

OpenBpfProgs

OpenBpfSkel

Opts 🔒

OwnedRef

Scheduler 🔒

The Scheduler facade owns the loaded skeleton, the struct_ops link, the stats server and the MLFQ tree daemon state; drives the run loop until shutdown or UEI exit.

StructOps

TrainResult 🔒

Result of one training run, handed back from the worker thread. The metrics are computed on the held-out slice so the publish gate and the reported numbers describe out-of-sample error.

TreeSample 🔒

One training sample, the mirror of struct mlfq_tree_sample.

Constants

MLFQ_IDLE_RESUME_LATENCY_US 🔒

MLFQ_MAX_CPUS 🔒

MLFQ_TREE_MAX_DEPTH 🔒

MLFQ_TREE_MAX_NODES 🔒

MLFQ_TREE_MIN_LEAF 🔒

MLFQ_TREE_MIN_PIDS 🔒

MLFQ_TREE_MIN_SAMPLES 🔒

MLFQ_TREE_PER_PID_CAP 🔒

MLFQ_TREE_RETRAIN_INTERVAL 🔒

MLFQ_TREE_WINDOW_MAX 🔒

NSEC_PER_USEC 🔒

SCHEDULER_NAME 🔒

Statics

DATA

Functions

build_skel_config

full_version 🔒

main 🔒

spawn_train_worker 🔒

Spawn the training worker and return its job and result channels.

split_holdout 🔒

Split the window into the fit slice (first 90%) and the held-out evaluation slice (last 10%). The daemon only trains once the window holds MLFQ_TREE_MIN_SAMPLES samples, so the holdout is never empty in production; a window too small for a meaningful 90/10 split (< 20 samples) is an error, which the caller treats as a skipped training round (log + keep the previous model) instead of silently training and evaluating on the same slice.

train_model 🔒

Fit a tree and compute the holdout metrics, on the training worker.

train_model_with_scratch 🔒

Fit a tree and compute holdout metrics reusing the scratch arena. The scratch buffers are cleared in place, so the second call with the same window size does not allocate.

tree_admit_pid 🔒

Admit one sample of pid into the window under the per-pid cap. Returns true when the sample is admitted and the pid’s count is incremented, false when the pid already holds its MLFQ_TREE_PER_PID_CAP share and the caller must drop the sample. Entries are pruned on eviction, not here: a pid at the cap keeps its entry until the window ages its samples out.

tree_distinct_pids 🔒

Number of distinct pids in a slice, the concentration input for the per-pid cap.

tree_evict_pid 🔒

Remove one sample of pid from the per-pid accounting when the window evicts its oldest sample, pruning the entry when the count reaches zero so the map cannot grow with retired pids.