How galpt/scx_timely works
scx_timely is a two-part sched_ext scheduler: a Rust userspace controller/loader and an eBPF kernel scheduling core. The repo also includes build-time code generation plus shell tooling for installation, enablement, and benchmarking.
High-level architecture
The system is organized around one main boundary:
• Userspace Rust crate: parses mode/CLI options, loads and configures the scheduler, and gathers status/metrics.
• Kernel eBPF program: implements the actual CPU scheduling behavior inside the Linux sched_ext framework.
Everything else in the repo either supports that boundary or exercises it.
Main runtime components
1) Rust userspace entrypoint
• src/main.rs is the executable entrypoint.
• It is the orchestration layer for:
- command-line parsing / mode selection
- choosing one of the built-in presets: desktop, powersave, or server
- applying controller knobs to the scheduler
- starting or attaching to the sched_ext program
- reporting scheduler state and health
This layer is the part the install and benchmark scripts invoke.
2) Scheduler statistics / observability
• src/stats.rs is the userspace-side metrics/reporting module.
• It is likely responsible for collecting and formatting scheduler state that is surfaced to the CLI, status script, and benchmark logs.
This is not the policy itself; it is the visibility layer around it.
3) Kernel scheduling logic
• src/bpf/main.bpf.c is the kernel-side BPF program.
• src/bpf/intf.h defines the C-side interface shared with userspace.
• This is where the actual sched_ext hooks and TIMELY-inspired policy live.
Architecturally, this is the core control loop:
• tasks are enqueued/dequeued by the kernel scheduler hooks
• queue delay is measured
• the TIMELY-style controller interprets delay and delay-gradient feedback
• slice gain / placement decisions are adjusted using additive increase, multiplicative decrease, and faster recovery behavior
The README makes clear that the policy is a TIMELY adaptation:
• RTT maps to task queue delay
• send-rate control maps to per-task slice gain
• Tlow / Thigh map to low/high queue-delay thresholds
4) Generated Rust-BPF interface
• src/bpf_intf.rs and src/bpf_skel.rs are generated or build-assisted bindings that connect the Rust loader to the BPF program.
• They form the typed boundary between Rust userspace and the kernel BPF object.
This is an important architectural seam: the Rust side configures and monitors the BPF scheduler, but the policy execution happens in kernel space.
Build-time architecture
5) Build script and BPF compilation
• build.rs is part of the build pipeline that prepares the BPF artifact and generated bindings.
• Cargo.toml / Cargo.lock define the Rust crate and its dependency graph.
The build process likely:
• compiles the BPF C source
• generates the skeleton/interface bindings
• packages the Rust binary with the BPF object so the userspace loader can deploy it at runtime
This is a standard sched_ext/libbpf-style split: the Rust binary is the controller/loader, while the BPF object is the in-kernel implementation.
Operational and deployment tooling
These files are not core scheduler logic, but they matter to how the system is used:
• install.sh, uninstall.sh
- integrate the scheduler with the local machine
- manage /etc/default/scx
- enable/disable scx.service
• enable_scx_timely.sh, status_scx_timely.sh
- reassert or inspect the active scheduler configuration
• install_benchmark_deps.sh, benchmark.sh, mini_benchmarker.sh, kill_benchmark.sh, mini_benchmarker_plot.py
- benchmark orchestration and result plotting
- compare baseline Linux, scx_cake, scx_bpfland, and scx_timely
These scripts sit outside the runtime data path, but they are important for understanding the repo as a scheduler project rather than a library.
Data flow
A simplified runtime flow looks like this:
1. A user or system service launches scx_timely through the install/enable scripts or directly via CLI.
2. src/main.rs selects a preset or applies overrides.
3. The Rust loader uses the generated skeleton/interface bindings to load and configure the BPF scheduler.
4. The kernel-side BPF program in src/bpf/main.bpf.c receives sched_ext events and makes per-task scheduling decisions.
5. The BPF program feeds back queue-delay information and controller state.
6. src/stats.rs and the CLI surface status/metrics to userspace.
7. Benchmark scripts can repeatedly start runs, collect metrics, and compare modes or schedulers.
Important boundaries
Userspace vs kernel space
This is the primary architectural boundary:
• Rust userspace = configuration, lifecycle, telemetry, deployment
• BPF kernel code = latency-sensitive scheduling policy
Policy vs presets
The scheduler uses one controller structure with different default parameter sets:
• desktop favors interactive responsiveness
• powersave is more conservative
• server widens placement/policy behavior for heavier throughput-oriented loads
So the repo has a single policy engine with multiple tuning profiles, not separate scheduler implementations.
Base scheduler inheritance
The project is explicitly built on upstream scx_bpfland.
That means:
• it inherits the bpfland scheduler structure
• it narrows and reinterprets the control layer around TIMELY-like feedback
• the repo is an adaptation layer, not a full rewrite
External/runtime dependencies that matter architecturally
• Linux sched_ext: the kernel framework that makes this a pluggable scheduler
• Upstream scx/scx_bpfland: the base scheduler behavior and workspace alignment
• systemd scx.service / /etc/default/scx: deployment and persistence mechanism on the host
• Benchmark utilities and plotting tools: used to validate and tune the scheduler across profiles
What to draw in an architecture diagram
A clear diagram would have these boxes:
• User / benchmark scripts
• Rust userspace scheduler binary
• Generated Rust-BPF interface
• Kernel eBPF scheduler
• Linux sched_ext / task scheduling hooks
• Metrics/status output path
And these flows:
• CLI/presets from scripts into the Rust binary
• configuration from Rust into BPF
• scheduling events and queue-delay feedback inside the kernel BPF loop
• status/metrics from scheduler back to userspace and benchmark logs
• install/enable scripts into systemd and /etc/default/scx
In short: scx_timely is a sched_ext scheduler with a Rust control plane and a BPF data-plane, where the kernel-side policy is a TIMELY-inspired adaptation layered on top of scx_bpfland.
Main entry points: main.bpf.c BPF core · main.rs Main · build.rs Build script · install.sh Install
Components 18
Runtime
Active scheduler control and kernel policy path
- Main · CLI entrypoint and scheduler orchestrator
src/main.rs - Stats · Userspace reporting and metrics formatting
src/stats.rs - BPF core · Kernel scheduler logic and TIMELY-style control loop
src/bpf/main.bpf.c - C interface · Shared userspace-kernel interface definitions
src/bpf/intf.h - sched_ext · Linux pluggable scheduler hooks and execution model
Build
Code generation and compilation support
- BPF iface · Typed Rust boundary to the kernel scheduler
src/bpf_intf.rs - Skeleton · Generated BPF skeleton used by the Rust loader
src/bpf_skel.rs - Build script · Prepares BPF artifacts and generated bindings
build.rs
Ops
Installation, enablement, and benchmarking tooling
- Scripts · Install, enable, status, and benchmark entrypoints
- systemd · Service management and persistent enablement
- Default cfg · /etc/default/scx configuration managed by scripts
- Install · Installs and configures the scheduler
install.sh - Uninstall · Removes scheduler integration
uninstall.sh - Enable · Reasserts active scx_timely configuration
enable_scx_timely.sh - Status · Inspects active scheduler state
status_scx_timely.sh - Benchmark · Runs comparative scheduler benchmarks
benchmark.sh - Mini bench · Small benchmark orchestration helper
mini_benchmarker.sh - Plot · Plots benchmark results
mini_benchmarker_plot.py
Connections 24
- Scripts → Main: launch/configure · Scripts invoke the Rust scheduler binary with presets or overrides
- Scripts → Install: install · Installation path for host integration
- Scripts → Enable: enable · Enables the active scheduler configuration
- Scripts → Status: inspect · Reads back scheduler state and health
- Scripts → Benchmark: benchmark · Benchmark entrypoint for comparative runs
- Scripts → Mini bench: orchestrate · Mini benchmark workflow helper
- Benchmark → Plot: visualize · Benchmark results are plotted for analysis
- Mini bench → Plot: visualize · Mini benchmark output is plotted
- Install → systemd: manage · Installs or enables the scheduler service
- Install → Default cfg: write · Populates host default configuration
- Uninstall → systemd: remove · Disables or removes the service integration
- Uninstall → Default cfg: cleanup · Removes host configuration
- Main → Stats: report · Surfaces scheduler health and metrics
- Main → Skeleton: load · Uses the generated skeleton to load the scheduler
- Main → BPF iface: configure · Uses typed bindings to set controller state
- Build script → Skeleton: generate · Produces the BPF skeleton during build
- Build script → BPF iface: generate · Produces Rust-side interface bindings during build
- Build script → BPF core: compile · Builds the BPF scheduler artifact
- Skeleton → BPF core: load artifact · Skeleton wraps the compiled kernel program
- BPF iface → C interface: mirror · Rust bindings mirror the shared C interface
- BPF core → C interface: shared ABI · Kernel code uses the shared interface definitions
- BPF core → sched_ext: runs on · Kernel policy executes through sched_ext hooks
- BPF core → Stats: emit state · Scheduler state is surfaced back to userspace reporting
- Main → BPF core: control loop · Userspace configures and monitors the kernel policy