Struct Scheduler 

pub(crate) struct Scheduler<'a> {

    pub(crate) skel: BpfSkel<'a>,
    pub(crate) struct_ops: Option<Link>,
    pub(crate) stats_server: StatsServer<(), Metrics>,
    pub(crate) webui_tx: Option<Sender<WebMetrics>>,
    pub(crate) webui_join: Option<JoinHandle<()>>,
    pub(crate) cpu_static: Vec<PerCpuMetrics>,
    pub(crate) cur_freq_khz: Vec<u64>,
    pub(crate) freq_read_at: Option<Instant>,
    pub(crate) started_at: Instant,
    pub(crate) pm_qos_fd: Option<File>,
    pub(crate) rb_mgr: RingBuffer<'static>,
    pub(crate) sample_rx: Receiver<TreeSample>,
    pub(crate) window: VecDeque<TreeSample>,
    pub(crate) pid_counts: HashMap<u32, u32>,
    pub(crate) tree_samples_cap_dropped: u64,
    pub(crate) last_train_at: Option<Instant>,
    pub(crate) train_tx: Sender<Vec<TreeSample>>,
    pub(crate) train_rx: Receiver<Result<TrainResult, Error>>,
    pub(crate) model: ModelMeta,
    pub(crate) train_snapshot_buf: Vec<TreeSample>,
    pub(crate) web_statics_buf: Vec<Option<PerCpuMetrics>>,
    pub(crate) web_per_cpu_buf: Vec<PerCpuMetrics>,
    pub(crate) op_lat_buf: Vec<u64>,
    pub(crate) wakeup_raw_buf: Vec<u8>,
    pub(crate) op_lat_raw_buf: Vec<u8>,
}

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.

Fields

skel: BpfSkel<'a>

struct_ops: Option<Link>

stats_server: StatsServer<(), Metrics>

webui_tx: Option<Sender<WebMetrics>>

webui_join: Option<JoinHandle<()>>

cpu_static: Vec<PerCpuMetrics>

cur_freq_khz: Vec<u64>

freq_read_at: Option<Instant>

started_at: Instant

pm_qos_fd: Option<File>

rb_mgr: RingBuffer<'static>

sample_rx: Receiver<TreeSample>

window: VecDeque<TreeSample>

pid_counts: HashMap<u32, u32>

tree_samples_cap_dropped: u64

last_train_at: Option<Instant>

train_tx: Sender<Vec<TreeSample>>

train_rx: Receiver<Result<TrainResult, Error>>

model: ModelMeta

train_snapshot_buf: Vec<TreeSample>

web_statics_buf: Vec<Option<PerCpuMetrics>>

web_per_cpu_buf: Vec<PerCpuMetrics>

op_lat_buf: Vec<u64>

wakeup_raw_buf: Vec<u8>

op_lat_raw_buf: Vec<u8>

Implementations

impl<'a> Scheduler<'a>

pub(crate) fn init( opts: &'a Opts, open_object: &'a mut MaybeUninit<OpenObject>, shutdown: Arc<AtomicBool>, ) -> Result<Self>

pub(crate) fn get_metrics(&mut self) -> Metrics

pub(crate) fn get_web_metrics(&mut self) -> WebMetrics

Web-metrics snapshot. The raw scheduler counters plus the per-CPU state and the runnable gauges, pushed to the web UI every run-loop iteration. Gauges only, no interval deltas.

pub(crate) fn read_cpu_state(&self, cpu: usize) -> mlfq_cpu_state

Read one CPU’s dynamic state from the per-CPU array map. A failed lookup or an unexpected value size yields an all-zero state.

pub(crate) fn read_rtdl_state(&self, cpu: usize) -> mlfq_rtdl_state

Read one CPU’s realtime-occupancy state from the per-CPU array map; a failed lookup yields an all-zero state (not occupied).

pub(crate) fn read_queue_runnable(&self) -> Vec<u64>

Tracked runnable tasks per queue (index 0 unused, 1..3 = Q1..Q3).

The gauge is the BPF-side mlfq_queue_runnable bss array, which counts the runnable tasks placed in each queue’s DSQs (the accounting contract is in intf.h next to the counters). Read through the generated bss type, so a layout change is a compile error rather than a silent misread.

pub(crate) fn read_llc_runnable(&self) -> Vec<u64>

Tracked runnable tasks per LLC domain (MLFQ_MAX_LLCS entries). Same contract and access path as read_queue_runnable.

pub(crate) fn exited(&self) -> bool

pub(crate) fn read_cpu_state_noalloc(&self, cpu: usize) -> mlfq_cpu_state

Stack-based read of per-CPU state without heap allocation. Uses the raw bpf_map_lookup_elem syscall with a stack buffer, so the 100 ms web snapshot does not allocate one Vec per CPU.

pub(crate) fn read_rtdl_state_noalloc(&self, cpu: usize) -> mlfq_rtdl_state

Stack-based read of RTDL state without heap allocation.

pub(crate) fn read_op_lat(&mut self) -> Vec<u64>

Sum the per-CPU op-latency histogram into a flat per-op vector (MLFQ_OP_LAT_OPS x MLFQ_OP_LAT_BUCKETS entries, op-major). The map is per-CPU so the BPF charges never contend. A failed lookup or an unexpected value size yields zeros for that entry.

pub(crate) fn read_wakeup_total(&mut self) -> u64

Sum the per-CPU lifetime wakeup totals from the mlfq_wakeup_stats map. Each CPU’s total is bumped atomically on the wakeup path, so this read is tear-free, and the u64 slots cannot wrap. A failed lookup yields zero. The observation-only contract holds, so the totals grow even while the adaptation is disabled.

pub(crate) fn run(&mut self, shutdown: Arc<AtomicBool>) -> Result<UserExitInfo>

pub(crate) fn ingest_sample(&mut self, s: TreeSample)

Fold one emitted sample into the sliding training window and kick a retrain on the cadence. On the first window that reaches the minimum training size, then every MLFQ_TREE_RETRAIN_INTERVAL.

The window admits at most MLFQ_TREE_PER_PID_CAP samples per pid. A pid that already holds its share is dropped here and counted in tree_samples_cap_dropped. The cap check runs before the window accounting, so a rejected sample never disturbs the per-pid counts, and the eviction bookkeeping below decrements the pid of the sample the window actually pops.

pub(crate) fn kick_training(&mut self)

Hand a snapshot of the window to the training worker.

The retrain cadence counts every kick, so a rejected model cannot turn into a per-sample retrain storm. try_send drops the kick when the worker is still busy with the previous fit, which the 60 s cadence makes rare.

pub(crate) fn poll_train_results(&mut self)

Collect the finished fits from the training worker and apply the publish quality gate to each.

pub(crate) fn apply_train_result(&mut self, res: TrainResult)

Commit a finished fit when it passes validation and the publish quality gate; otherwise keep the previous model.

The gate and the meta computation are pure functions in mlfq_tree (mlfq_tree::should_publish, mlfq_tree::tree_meta), which the unit tests cover.

pub(crate) fn publish_tree( &mut self, tree: &SerializedTree, gen: u64, ) -> Result<()>

Publish a validated tree into the inactive map entry and commit the meta last.

The full map value is written (live nodes at the front, zeroed tail), so a shrinking tree never leaves stale nodes behind the new node count. A release fence orders the map-value write before the meta write, which flips the active entry, bumps the generation and sets the trained bit: a BPF reader that loaded the meta once sees either the old tree or the fully committed new one, never a partially written one.

The protocol is sound at the 60 s publish cadence: a reader could only observe a torn tree if two publishes completed within one tree walk, and each walk is a few dozen memory reads while a publish moves up to 2048 nodes, so two consecutive publishes cannot complete inside one walk. The consequence of the theoretical race is one mispredicted burst, which the queue-band nets absorb. The walk masks every index to the buffer bound, so it is never a memory-safety issue.

Trait Implementations

impl Drop for Scheduler<'_>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.