qumun

README

qumun - A Custom Linux Scheduler Framework using eBPF and Go

qumun is a scheduler development framework that empowers developers to build custom Linux schedulers using Golang and eBPF.

The name qumun comes from the Bunun language (an Indigenous people of Taiwan), where it means “heart.” Just as the heart powers and sustains the body, a scheduler is the core heartbeat of the operating system — orchestrating tasks, balancing workloads, and keeping everything alive and running.

By choosing this name, we hope to highlight both the technical role of a scheduler and also share a piece of Taiwan’s Indigenous culture with the global open-source community.

DEMO

Overview

This scheduler is designed to prioritize interactive workloads over background CPU-intensive tasks. It's particularly suitable for:

• Low-latency interactive applications
• Gaming
• Video conferencing
• Live streaming

The scheduler consists of two main components:

1. A BPF component that implements low-level sched-ext functionalities
2. A user-space scheduler written in Go with scx_goland_core that implements the actual scheduling policy

Key Features

• Virtual runtime (vruntime) based scheduling
• Latency-sensitive task prioritization
• Dynamic time slice adjustment
• CPU topology aware task placement
• Automatic idle CPU selection

How It Works

The scheduling policy is based on virtual runtime:

• Each task receives a time slice of execution (slice_ns)
• The actual execution time is adjusted based on task's static priority (weight)
• Tasks are dispatched from lowest to highest vruntime
• Latency-sensitive tasks receive priority boost based on voluntary context switches

Building

Prerequisites:

• Go 1.22+
• LLVM/Clang 17+
• libbpf
• Linux kernel 6.12+ with sched_ext support

Usage

Setting Up Dependencies

First, clone the required dependencies:

make dep
git submodule init
git submodule sync
git submodule update
cd scx
cargo build --release -p scx_rustland

This will clone libbpf and the custom libbpfgo fork needed for the project.

Building the Scheduler

Build the scheduler with:

make build

This compiles the BPF program, builds libbpf, generates the skeleton, and builds the Go application.

Testing the Scheduler

To test the scheduler in a virtual environment using kernel v6.12.2:

make test

This uses vng (virtual kernel playground) to run the scheduler with the appropriate kernel version.

Running in Production

To run the scheduler on your system:

sudo ./main

The scheduler will run until terminated with Ctrl+C (SIGINT) or SIGTERM.

Debugging

If you need to inspect the BPF components, you can use:

sudo bpftool prog list            # List loaded BPF programs
sudo bpftool map list             # List BPF maps
sudo cat /sys/kernel/debug/tracing/trace_pipe # View BPF trace output

Stress Testing by using stress-ng

stress-ng -c 20 --timeout 20s --metrics-brief

License

This software is distributed under the terms of the Apache License 2.0.

Contributing

Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.