# galpt/infinity-scheduler architecture

> Architecture diagram of the GitHub repository galpt/infinity-scheduler, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/galpt/infinity-scheduler
- Repository: https://github.com/galpt/infinity-scheduler

## Overview

1. **What this repository is**
   - `infinity-scheduler` is a **Linux kernel scheduler patch set**, not a standalone daemon or userspace service.
   - Its architectural boundary is the upstream kernel scheduler: it modifies **CFS/EEVDF** and **RT scheduling** behavior in-kernel.

2. **Main functional subsystem: the scheduling policy**
   - The policy centers on a **fair-share budget model** driven by an **EMA (exponential moving average)** of recent runtime.
   - The key idea is a feedback loop: **more runtime increases EMA, which shortens future slices; sleeping decays EMA, restoring responsiveness**.

3. **Core code location**
   - `src/infinity_sched.c` is the reference implementation of the scheduling logic.
   - `src/infinity_sched.h` defines the public-facing kernel API used by the patch: constants, sysctl declarations, and function prototypes.
   - Treat `src/` as the **algorithm source of truth** for the kernel modifications.

4. **Where it hooks into the kernel**
   - The README maps Infinity into specific scheduler touchpoints:
     - fair scheduling: `update_deadline()`, `update_curr()`, `enqueue_task_fair()`, `dequeue_task_fair()`, `task_fork_fair()`, `pick_next_entity()`
     - RT scheduling: `update_curr_rt()`, `dequeue_task_rt()`, `__enqueue_rt_entity()`
     - v3-specific wakeup behavior: `place_entity()`, `pick_eevdf()`
   - These hooks are the main architectural integration points between Infinity and the upstream scheduler.

5. **Fair-scheduling data flow**
   - A task’s runtime history feeds the EMA state.
   - That EMA drives:
     - **slice length** via `infinity_slice()`
     - **deadline/wakeup positioning** via `infinity_wakeup()` and `infinity_wakeup_scale()`
     - **task initialization** via `infinity_fork_init()`
   - The result is a scheduler tree where CPU-bound tasks are progressively throttled while interactive sleepers regain advantage.

6. **RT-scheduling data flow**
   - RT tasks are not separate from the model; they are also modulated by the same EMA concept.
   - `update_curr_rt()` and `dequeue_task_rt()` adjust RT state as tasks run or block.
   - In v3, `__enqueue_rt_entity()` also uses **EMA-modulated queue placement**, so RT behavior is influenced by recent execution intensity rather than a fixed priority model alone.

7. **Wakeup and interactivity behavior**
   - Sleep/wakeup transitions are important boundaries in the design.
   - On sleep, tasks record timing and let EMA decay; on wake, the scheduler can give them **shorter virtual slices** so they reach an earlier deadline in the EEVDF tree.
   - The README also highlights a **futex-wait bypass** path: interactive waiters can skip slice protection so they can preempt sooner at the next scheduling point.

8. **Configuration surface**
   - Runtime control is exposed through **kernel sysctl parameters** under `kernel.infinity_*`.
   - The main knobs are:
     - `infinity_carriage_ns` — the base fair-share window
     - `infinity_smt_divisor` — SMT-specific slice adjustment
     - `infinity_running` — read-only active flag
     - `infinity_reset` — reset trigger
   - This makes the policy tunable without changing the kernel image, but still keeps all values clamped in-kernel.

9. **Repository packaging by kernel version**
   - `patches/stable/` contains **versioned patch bundles** for specific kernel releases such as `linux-6.18-infinity`, `linux-7.0.12-infinity`, and `linux-7.1-infinity`.
   - This is the release/distribution layer of the repo: the same scheduler concept is adapted into multiple kernel baselines.

10. **Tooling and automation layer**
   - `tools/install-infinity-scheduler.sh` is the main operational entry point for building and installing the patched kernel.
   - `tools/build-kernel.sh` supports standalone kernel builds.
   - `tools/adapt-patches.py`, `tools/fix-patch-format.py`, and `tools/fix-patch-counts.py` support patch maintenance across kernel versions.
   - These tools exist to keep the patch series portable as upstream kernel internals move.

11. **Operational lifecycle**
   - The expected flow is: obtain the correct patch set, build a kernel with the Infinity changes, install it, and boot into the `-infinity` kernel.
   - Runtime verification happens through **`uname -r`**, **sysctl state**, and **kernel log output**.
   - This shows the project’s runtime boundary clearly: once booted, Infinity lives entirely inside the Linux kernel scheduler.

12. **Architectural summary for diagramming**
   - A useful diagram would show:
     - **Userspace/sysctl** feeding tunables into the kernel
     - **Task execution / sleep / wake events** feeding EMA state
     - **Infinity scheduling logic** computing slices, deadlines, and RT placement
     - **Upstream kernel scheduler structures** receiving the modified decisions
     - **Patch/tooling layer** as the build-time path that injects Infinity into specific kernel versions

Main entry points: [`src/infinity_sched.c`](https://github.com/galpt/infinity-scheduler/blob/v3/src/infinity_sched.c) (Scheduler core), [`patches/stable/linux-6.18-infinity/0001-infinity-scheduler.patch`](https://github.com/galpt/infinity-scheduler/blob/v3/patches/stable/linux-6.18-infinity/0001-infinity-scheduler.patch) (6.18 bundle), [`tools/build-kernel.sh`](https://github.com/galpt/infinity-scheduler/blob/v3/tools/build-kernel.sh) (Build script), [`tools/install-infinity-scheduler.sh`](https://github.com/galpt/infinity-scheduler/blob/v3/tools/install-infinity-scheduler.sh) (Install script)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_policy["Policy core"]
  node_n_sched_c["Scheduler core<br/>kernel C code<br/>[infinity_sched.c]"]
  node_n_sched_h["Kernel API<br/>kernel header<br/>[infinity_sched.h]"]
  node_n_ema(("EMA budget<br/>policy model"))
  node_n_slices["Slice control<br/>policy function"]
  node_n_wakeup["Wakeup logic<br/>policy function"]
  node_n_fork["Fork init<br/>policy function"]
  node_n_rt["RT modulation<br/>policy function"]
  node_n_sysctl[("Sysctl knobs<br/>runtime config")]
end

subgraph group_grp_kernel["Kernel hooks"]
  node_n_fair_hooks{{"Fair hooks<br/>kernel integration"}}
  node_n_rt_hooks{{"RT hooks<br/>kernel integration"}}
  node_n_eevdf_hooks{{"EEVDF wakeups<br/>kernel integration"}}
  node_n_kernel["Kernel scheduler<br/>upstream kernel"]
end

subgraph group_grp_package["Patch bundles"]
  node_n_patch_618["6.18 bundle<br/>patch bundle"]
  node_n_patch_7012["7.0.12 bundle<br/>patch bundle"]
  node_n_patch_71["7.1 bundle<br/>patch bundle"]
end

subgraph group_grp_tools["Tooling"]
  node_n_install["Install script<br/>shell script"]
  node_n_build["Build script<br/>shell script<br/>[build-kernel.sh]"]
  node_n_adapt["Adapt patches<br/>python tool<br/>[adapt-patches.py]"]
  node_n_fixfmt["Fix format<br/>python tool"]
  node_n_fixcounts["Fix counts<br/>python tool"]
end

node_n_readme["README<br/>docs<br/>[README.md]"]

node_n_readme -->|"describes"| node_n_sched_c
node_n_readme -->|"packages"| node_n_patch_618
node_n_sched_c -->|"uses"| node_n_sched_h
node_n_sched_c -->|"maintains"| node_n_ema
node_n_ema -->|"drives"| node_n_slices
node_n_ema -->|"drives"| node_n_wakeup
node_n_ema -->|"drives"| node_n_rt
node_n_sched_c -->|"implements"| node_n_fork
node_n_sched_c -->|"reads"| node_n_sysctl
node_n_sysctl -->|"configures"| node_n_kernel
node_n_sched_c -->|"hooks"| node_n_fair_hooks
node_n_sched_c -->|"hooks"| node_n_rt_hooks
node_n_sched_c -->|"hooks"| node_n_eevdf_hooks
node_n_fair_hooks -->|"modifies"| node_n_kernel
node_n_rt_hooks -->|"modifies"| node_n_kernel
node_n_eevdf_hooks -->|"modifies"| node_n_kernel
node_n_patch_618 -->|"patches"| node_n_kernel
node_n_patch_7012 -->|"patches"| node_n_kernel
node_n_patch_71 -->|"patches"| node_n_kernel
node_n_install -->|"invokes"| node_n_build
node_n_install -->|"uses"| node_n_patch_618
node_n_build -->|"consumes"| node_n_patch_618
node_n_adapt -->|"updates"| node_n_patch_7012
node_n_fixfmt -->|"normalizes"| node_n_patch_618
node_n_fixcounts -->|"repairs"| node_n_patch_618
node_n_build -->|"produces"| node_n_kernel

click node_n_readme "https://github.com/galpt/infinity-scheduler/blob/v3/README.md"
click node_n_sched_c "https://github.com/galpt/infinity-scheduler/blob/v3/src/infinity_sched.c"
click node_n_sched_h "https://github.com/galpt/infinity-scheduler/blob/v3/src/infinity_sched.h"
click node_n_patch_618 "https://github.com/galpt/infinity-scheduler/blob/v3/patches/stable/linux-6.18-infinity/0001-infinity-scheduler.patch"
click node_n_patch_7012 "https://github.com/galpt/infinity-scheduler/blob/v3/patches/stable/linux-7.0.12-infinity/0001-infinity-scheduler.patch"
click node_n_patch_71 "https://github.com/galpt/infinity-scheduler/blob/v3/patches/stable/linux-7.1-infinity/0001-infinity-scheduler.patch"
click node_n_install "https://github.com/galpt/infinity-scheduler/blob/v3/tools/install-infinity-scheduler.sh"
click node_n_build "https://github.com/galpt/infinity-scheduler/blob/v3/tools/build-kernel.sh"
click node_n_adapt "https://github.com/galpt/infinity-scheduler/blob/v3/tools/adapt-patches.py"
click node_n_fixfmt "https://github.com/galpt/infinity-scheduler/blob/v3/tools/fix-patch-format.py"
click node_n_fixcounts "https://github.com/galpt/infinity-scheduler/blob/v3/tools/fix-patch-counts.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_sched_c,node_n_sched_h,node_n_ema,node_n_slices,node_n_wakeup,node_n_fork,node_n_rt,node_n_sysctl toneBlue
class node_n_fair_hooks,node_n_rt_hooks,node_n_eevdf_hooks,node_n_kernel toneAmber
class node_n_patch_618,node_n_patch_7012,node_n_patch_71 toneMint
class node_n_install,node_n_build,node_n_adapt,node_n_fixfmt,node_n_fixcounts toneRose
class node_n_readme toneNeutral
```

## Components

### Policy core

EMA-driven scheduler logic and tunables

- [Scheduler core](https://github.com/galpt/infinity-scheduler/blob/v3/src/infinity_sched.c): kernel C code · Reference implementation of Infinity scheduling policy · `src/infinity_sched.c`
- [Kernel API](https://github.com/galpt/infinity-scheduler/blob/v3/src/infinity_sched.h): kernel header · Constants, sysctls, and scheduler function prototypes · `src/infinity_sched.h`
- **EMA budget**: policy model · Tracks recent runtime to shape future CPU share
- **Slice control**: policy function · Computes fair-share slice length from budget state
- **Wakeup logic**: policy function · Adjusts wakeup placement and deadline advantage
- **Fork init**: policy function · Initializes task state for new forks
- **RT modulation**: policy function · Applies EMA-aware behavior to real-time tasks
- **Sysctl knobs**: runtime config · Kernel.infinity_* tunables and reset controls

### Kernel hooks

Upstream CFS/EEVDF and RT integration points

- **Fair hooks**: kernel integration · CFS/EEVDF touchpoints for runtime, enqueue, dequeue, fork, and pick
- **RT hooks**: kernel integration · RT scheduling touchpoints for runtime and queue state
- **EEVDF wakeups**: kernel integration · Wakeup placement and selection changes in v3 behavior
- **Kernel scheduler**: upstream kernel · Modified CFS, EEVDF, and RT scheduler behavior

### Patch bundles

Versioned patch series for kernel releases

- [6.18 bundle](https://github.com/galpt/infinity-scheduler/blob/v3/patches/stable/linux-6.18-infinity/0001-infinity-scheduler.patch): patch bundle · Stable patch series for linux-6.18-infinity · `patches/stable/linux-6.18-infinity/0001-infinity-scheduler.patch`
- [7.0.12 bundle](https://github.com/galpt/infinity-scheduler/blob/v3/patches/stable/linux-7.0.12-infinity/0001-infinity-scheduler.patch): patch bundle · Stable patch series for linux-7.0.12-infinity · `patches/stable/linux-7.0.12-infinity/0001-infinity-scheduler.patch`
- [7.1 bundle](https://github.com/galpt/infinity-scheduler/blob/v3/patches/stable/linux-7.1-infinity/0001-infinity-scheduler.patch): patch bundle · Stable patch series for linux-7.1-infinity · `patches/stable/linux-7.1-infinity/0001-infinity-scheduler.patch`

### Tooling

Build, install, and patch-maintenance scripts

- [Install script](https://github.com/galpt/infinity-scheduler/blob/v3/tools/install-infinity-scheduler.sh): shell script · Builds and installs the patched kernel · `tools/install-infinity-scheduler.sh`
- [Build script](https://github.com/galpt/infinity-scheduler/blob/v3/tools/build-kernel.sh): shell script · Standalone kernel build helper · `tools/build-kernel.sh`
- [Adapt patches](https://github.com/galpt/infinity-scheduler/blob/v3/tools/adapt-patches.py): python tool · Port patch series across kernel versions · `tools/adapt-patches.py`
- [Fix format](https://github.com/galpt/infinity-scheduler/blob/v3/tools/fix-patch-format.py): python tool · Normalizes patch formatting · `tools/fix-patch-format.py`
- [Fix counts](https://github.com/galpt/infinity-scheduler/blob/v3/tools/fix-patch-counts.py): python tool · Updates patch counts and metadata · `tools/fix-patch-counts.py`

### Other components

- [README](https://github.com/galpt/infinity-scheduler/blob/v3/README.md): docs · Architecture and usage guide · `README.md`

## Connections

- README → Scheduler core: describes · Documents the scheduler implementation and behavior
- README → 6.18 bundle: packages · Explains versioned patch bundles
- Scheduler core → Kernel API: uses · Implementation depends on shared kernel-facing declarations
- Scheduler core → EMA budget: maintains · Updates runtime history and decay state
- EMA budget → Slice control: drives · Budget state determines future slice length
- EMA budget → Wakeup logic: drives · Budget state influences wakeup placement
- EMA budget → RT modulation: drives · Budget state modulates RT behavior
- Scheduler core → Fork init: implements · Initializes task state on fork
- Scheduler core → Sysctl knobs: reads · Consumes tunables and reset state
- Sysctl knobs → Kernel scheduler: configures · Exposes runtime control inside the kernel scheduler
- Scheduler core → Fair hooks: hooks · Integrates into CFS scheduling paths
- Scheduler core → RT hooks: hooks · Integrates into RT scheduling paths
- Scheduler core → EEVDF wakeups: hooks · Integrates wakeup and selection behavior
- Fair hooks → Kernel scheduler: modifies · Changes fair-scheduler decisions in-kernel
- RT hooks → Kernel scheduler: modifies · Changes real-time scheduling behavior
- EEVDF wakeups → Kernel scheduler: modifies · Changes EEVDF wakeup and pick behavior
- 6.18 bundle → Kernel scheduler: patches · Applies Infinity changes to a kernel baseline
- 7.0.12 bundle → Kernel scheduler: patches · Applies Infinity changes to a kernel baseline
- 7.1 bundle → Kernel scheduler: patches · Applies Infinity changes to a kernel baseline
- Install script → Build script: invokes · Install flow builds the patched kernel
- Install script → 6.18 bundle: uses · Selects a versioned patch bundle for installation
- Build script → 6.18 bundle: consumes · Build helper works with patched kernel sources
- Adapt patches → 7.0.12 bundle: updates · Ports patch series across moving kernel internals
- Fix format → 6.18 bundle: normalizes · Maintains patch formatting consistency
- Fix counts → 6.18 bundle: repairs · Maintains patch metadata and counts
- Build script → Kernel scheduler: produces · Build output is the patched kernel image