SRQ_BORING: The default — just a regular thread being placed on the queue, nothing unusual.

SRQ_YIELDING: The thread said "I'm done for now, let someone else go." The scheduler places it at the back of its priority queue.

SRQ_INTR: This thread was woken by a hardware interrupt (like a network packet arriving). It may need to run urgently.

SRQ_PREEMPTED: A higher-priority thread showed up, so this one was forcibly pulled off the CPU. Gets special treatment when re-queued.

SRQ_HOLD / SRQ_HOLDTD (FreeBSD 14+): Lock-management flags that control which locks are held when the function returns — important for avoiding lock-order violations.

Increment the tick counter (ts_cpticks) — this tracks raw clock ticks for the current scheduling window.

Add 1 to the estimated CPU usage (ts_estcpu) and clamp it to a maximum value so it does not overflow.

Every Nth tick (where N = INVERSE_ESTCPU_WEIGHT, typically 8), recalculate the thread's priority using the decay formula above.

Priority does not change on every tick — it is batched for efficiency. The thread's position in the run queue only shifts every 8 ticks.

ts_pctcpu: Percentage of CPU used — shown in ps output as the CPU% column.

ts_cpticks: Raw clock ticks consumed in the current window. Feeds the decay formula.

ts_slptime: How long this thread has been sleeping. After sleeping, the next wakeup gets a priority boost.

ts_slice (FB11+): Remaining ticks before the scheduler forces a switch. Adds explicit time-slicing.

ts_estcpu (FB12+): Moved from the process struct into the per-thread struct for finer-grained accounting.

Get the thread's scheduler state, which tracks time spent running vs. sleeping.

If the thread has spent more time running than sleeping, it gets a high score (less interactive — it is a CPU hog).

If the thread sleeps more than it runs, it gets a low score (more interactive — waiting for user input or I/O).

The SCHED_INTERACT_HALF constant creates a threshold: scores above it mark batch threads, below mark interactive ones.

Interactive threads receive a priority boost, keeping them responsive even under heavy load.

64 queues, each covering 4 priority values. Priority 0–3 → queue 0, priority 4–7 → queue 1, and so on.

rq_status: a bitmask with one bit per queue — set means "this queue has threads, check it."

Finding the highest-priority runnable thread = finding the lowest-set bit in rq_status. That is a single bsf (bit-scan forward) instruction — O(1).

The downside: 4 different priorities share a queue, so a priority-5 thread might wait behind priority-7 threads at the same queue slot.

256 queues — one per priority level. Priority 5 → queue 5, no sharing.

rq_status: now 4 × 64-bit words = 256 bits total. One bit per queue, just more of them.

Finding the highest-priority thread: scan the 4 words with __builtin_ctzl() (count trailing zeros) — still effectively O(1).

✅ Eliminates intra-band priority inversion: no thread with priority 5 waits behind priority 7 in the same slot.

Convert the thread's numeric priority to a queue index. In FB10-15, divide by 4 so priorities 0–3 share queue 0. In FB16, it is 1:1.

Get a pointer to the target queue head in the run queue array.

If the thread is yielding (gave up CPU voluntarily), add it to the tail — it waits behind others at the same priority.

Otherwise (preempted or newly runnable), add it to the head — it runs first when its priority comes up.

Set the corresponding bit in the status bitmask to indicate this queue is non-empty. Enables O(1) queue selection via bit-scan instructions.

Get the currently running thread (curthread is a per-CPU global — fast, no locking needed).

Call sched_switch(), which asks the scheduler to pick the next thread. The scheduler calls cpu_switch() under the hood.

The key insight: cpu_switch() does not return to us — it returns to the new thread's saved state. We only resume when some future scheduling decision picks us again.

When we are re-scheduled (maybe milliseconds or seconds later), we update our CPU ID to reflect which CPU we are now running on — we might have migrated to a different core!

This is a vtable — the same design pattern as C++ virtual functions, but in plain C.

Each scheduler (4BSD, ULE, or a future third-party one) fills in this struct with its own function pointers.

The kernel calls sched_add(). The shim resolves this to whichever scheduler's .sched_add pointer was set at boot.

With ~45 function pointers, the interface covers everything from creating threads (sched_fork) to making scheduling decisions (sched_choose).

DECLARE_SCHEDULER does two things: registers the scheduler instance in a linker set, and generates IFUNC trampoline stubs.

DATA_SET(schedulers, si) places the instance in a special linker section so the kernel can discover all available schedulers at boot.

SCHED_DEFINE_IFUNCS generates one IFUNC resolver per scheduler function. At boot, the linker resolves each to the active scheduler's function pointer.

Setting kern.sched.name=ULE in /boot/loader.conf selects the scheduler — no recompilation needed.

enqueue probe: Fires every time a thread enters the run queue. Great for seeing which processes are most active.

on-cpu aggregation: Counts scheduling events per process, reports every 5 seconds. Shows who the CPU-hungriest processes are in production.

off-cpu/on-cpu latency: Measures how long each thread waits between being switched out and switched back in. A distribution (quantize) shows if outliers exist.

change-pri trace: Shows priority changes as they happen. Useful for diagnosing unexpected priority boosts or inversions.

All probes fire at near-zero cost when not active — SDT probes are nop instructions when DTrace is not running.