Skip to content
Linux Systems Field Manual

linux/kernel/sched/sched.h

Imported from _research/manual-study-linux/file-notes/linux__kernel__sched__sched.h.md.

File Notes: kernel/sched/sched.h

Status: reviewed.

Purpose

Defines scheduler-private data structures and callback contracts. This is where the scheduler’s C implementation exposes the shape of a runqueue and the operation table that fair, RT, deadline, idle, and extension classes plug into.

Key Types And Functions

  • struct rq: the main per-CPU runqueue object.
  • struct rq_flags: pinned runqueue lock context and clock-update state.
  • struct sched_class: scheduler class vtable with lock-precondition comments.

Data Flow

struct rq stores hot scheduling state for one CPU: runnable counts, wakeup flags, CPU capacity, current/donor pointers, idle task, switch count, the runqueue spinlock, and embedded class queues (cfs, rt, dl, and optional extension state). Scheduler core code locks an rq, updates clocks and class queues, asks a class to choose a task, then publishes the selected task through the runqueue.

The scheduler does not hard-code every policy decision into core.c. struct sched_class is the dispatch contract. It includes callbacks for enqueue, dequeue, yield, wakeup preemption, balance, picking, previous/next task transitions, CPU selection, migration, ticks, fork/death hooks, and class-change hooks.

Invariants And Safety Contracts

  • Multi-runqueue locking must be ordered by ascending runqueue address.
  • Many sched_class callbacks document required locks directly in the field comments.
  • rq_flags carries interrupt flags and pinned-lock clock-update state across paths that unpin and repin the runqueue lock.
  • Per-CPU runqueue locality is fundamental: global behavior is built from coordinated local queues plus migration/load-balancing paths.

Rust Translation Guidance

Represent runqueue access with guard types that encode whether the runqueue is locked and whether interrupts/preemption are disabled. If scheduler classes are dynamic, model sched_class as a sealed trait or static vtable whose method types make lock requirements explicit. Keep class queues embedded in the CPU runqueue object instead of spreading policy state globally.

AI-Native Systems Guidance

Agent runtimes should expose their scheduling policy through explicit class interfaces: enqueue job, dequeue job, preempt check, pick job, account current, and class-change hooks. The scheduler API should carry resource-lock and authority requirements as typed contracts rather than comments in prompts.

Evidence

  • struct rq is introduced as the main per-CPU runqueue with multi-runqueue lock ordering at kernel/sched/sched.h:1128-1135.
  • Hot runqueue fields include runnable counts, wakeup flags, CPU capacity, current/donor pointers, idle task, switch count, lock, and embedded cfs, rt, and dl queues at kernel/sched/sched.h:1135-1189.
  • struct rq_flags stores interrupt flags, pin cookie, and clock update state at kernel/sched/sched.h:1849-1858.
  • struct sched_class begins at kernel/sched/sched.h:2585; callback comments list lock requirements for enqueue, dequeue, wakeup, balance, pick, and migration paths at kernel/sched/sched.h:2591-2653.