schedkit

A user-space thread scheduling framework for Linux.

schedkit provides a Python-based framework for implementing and evaluating custom thread scheduling policies. It monitors running processes and adjusts thread-to-CPU affinities according to configurable scheduling algorithms.

Features

• Pluggable scheduler architecture: Easily implement custom scheduling policies
• Hardware performance counter integration: Use perf events to make scheduling decisions
• NUMA-aware scheduling: Built-in support for NUMA topology awareness
• Multiple built-in schedulers: FAR, CLOSE, AsymSched, SAM, SAS

Requirements

• Linux (tested on Ubuntu 20.04+)
• Python 3.10+
• Root privileges or CAP_SYS_NICE capability (for setting thread affinities)

Optional

• perf tool (for hardware performance counter collection)
• NUMA support in kernel (for NUMA-aware schedulers)

Installation

# Clone the repository
git clone https://github.com/open-s4c/schedkit.git
cd schedkit

# Install dependencies
pip install -r requirements.txt

# Or install as a package
pip install -e .

Usage

# Run with a specific scheduler
python schedkit.py run <scheduler> [options]

# Available schedulers: Normal, FAR, CLOSE, AsymSched, SAM, SAS

# Example: Run FAR scheduler filtering for db_bench processes
python schedkit.py run FAR --filter=db_bench --interval=0.2

# Cleanup any leftover state
python schedkit.py cleanup

Options

Option	Description
--filter=NAMES	Comma-separated list of process names to manage
--interval=SECS	Scheduling interval in seconds (default: 1.0)
--cpu-percentage=PCT	Minimum CPU usage to consider a thread relevant
--cpu-order=CPUS	Comma-separated list of CPUs in preferred order

Built-in Schedulers

Scheduler	Description
Normal	No intervention (uses default Linux scheduler)
FAR	Spreads threads across NUMA nodes for memory bandwidth
CLOSE	Packs threads close together for cache locality
AsymSched	NUMA-aware asymmetric scheduling
SAM	Sharing-Aware Mapping (memory bandwidth aware)
SAS	Sharing-Aware Scheduling

Project Structure

schedkit/
├── schedkit.py              # Main entry point (CLI)
├── schedulers/
│   ├── common/              # Framework base classes
│   │   ├── scheduler.py     # Base Scheduler class
│   │   ├── framework.py     # Thread monitoring utilities
│   │   └── ThreadMapping.py # Thread-to-CPU mapping
│   ├── asymsched/           # AsymSched implementation
│   ├── SAM/                 # SAM scheduler implementation
│   ├── SAS/                 # SAS scheduler implementation
│   ├── FAR/                 # FAR scheduler implementation
│   ├── CLOSE/               # CLOSE scheduler implementation
│   └── ONLY/                # Single-CPU scheduler
└── requirements.txt

Implementing a Custom Scheduler

Create a new scheduler by subclassing the Scheduler class:

from schedulers.common.scheduler import Scheduler
from schedulers.common.ThreadMapping import ThreadMapping

class MyScheduler(Scheduler):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)

    def schedule_threads(self, threads_list):
        """
        Implement your scheduling logic here.

        Args:
            threads_list: List of thread groups to schedule

        Returns:
            ThreadMapping: Mapping of threads to CPU sets
        """
        mapping = ThreadMapping()
        # Your scheduling logic here
        return mapping

Authors

• Mats Van Molle (mats.van.molle@vub.be)
• Seppe Wyns (mail@seppe.io)
• Thomas Guillaume Vandermotten (thomas.guillaume.vandermotten@vub.be)
• Antonio Paolillo (antonio.paolillo@vub.be)

Vrije Universiteit Brussel (VUB)

License

MIT License - see LICENSE for details.

Acknowledgments

This project implements scheduling algorithms from the following research:

• SAM: Tam, D., Azimi, R., & Stumm, M. (2007). Thread clustering: sharing-aware scheduling on SMP-CMP-SMT multiprocessors.
• AsymSched: Various NUMA-aware scheduling research.