Home /Modules/web-server-technology/CPU-WARM.md

CPU-WARM.md

web-server-technology/docs/CPU-WARM.md · 101 line(s) · markdown

CPU keep-warm idle floor

A modest, scientifically-bounded background load that keeps each of the server's CPUs lightly busy — a target band of ~11% (floor) up to 14% (ceiling) per core — even when no request traffic is present. The intent is to keep the server warm: discourage cores from dropping into deep idle C-states / low P-states, so the first request after a quiet period does not pay a frequency-ramp / cold-path penalty.

Policy

The feature is ON by default (a deliberate, stated operational preference: keep the server warm). An administrator may disable it with --no-warm, or retune the band. The warmer runs one thread per CPU, with the thread count being the detected online CPU count clamped to the range 1–16.

Why a closed-loop controller, not a fixed sleep ratio

"11% of a CPU" is not a fixed busy/sleep ratio. Measured utilization drifts with frequency scaling, turbo, and scheduler placement, so a hard-coded duty cycle reads as very different utilization across machines. The warmer is therefore a closed-loop controller: each per-core thread measures its own CPU time (CLOCK_THREAD_CPUTIME_ID) against wall-clock time (CLOCK_MONOTONIC) over a short window and adjusts its busy/idle duty cycle with a proportional controller to converge into the configured band. It targets the middle of the band (12.5% for the 11–14 default) so normal jitter stays inside the edges.

The controller is the defensible way to actually land near 11–14% rather than hope a magic ratio does. The convergence test (cpu_warmer-test.cpp) measures the achieved utilization two independent ways (the controller's own estimate and process-level CPU time ÷ thread count) and asserts both land in band; on the build host both read ~12.5%.

Deference to real work

Warmer threads run at the lowest practical scheduling class (SCHED_IDLE on Linux where available). They fill otherwise-idle time only; genuine request handling always preempts them, so the floor never steals measurable throughput. The busy phase does a small, non-optimizable arithmetic kernel (fed through a volatile sink) that touches the pipeline and caches without allocating or doing any I/O.

Bounds (always enforced)

The configuration is clamped into a safe range so it can never become a runaway hot loop:

Control surface (startup flags or config file)

--no-warm            # administrator disables the keep-warm floor
--warm-floor N       # target floor percent per core (default 11)
--warm-ceiling N     # target ceiling percent per core (default 14)
--warm-cores N       # max warmer threads, clamped 1..16 (default 16)
# or in the config file:
cpu-warm         = on        # on (default) | off
cpu-warm-floor   = 11
cpu-warm-ceiling = 14
cpu-warm-cores   = 16

The command line overrides the config file.

Observability

/__sleela/status reports:

"cpu_warm": true,
"cpu_warm_floor_pct": 11,
"cpu_warm_ceiling_pct": 14,
"cpu_warm_cores": 16,
"cpu_warm_measured_pct": 12.50

and the startup log records cpu-warm=on floor=11% ceiling=14% cores=N (or cpu-warm=off (administrator disabled)).

Honest caveats

Tests