Fix frame rate limiting blocking forever when the clock cannot observe sleep

[simon112]

(AI-authored fix; verification described at the bottom. Builds on #2247, whose branch this one is based on: only the second commit is new here, and the first must land first.)

Problem

The frame rate limiting loop in flecs_insert_sleep sleeps a fixed interval and remeasures until the frame reaches the target time. When the clock does not advance during a sleep, the loop never exits: on a clock that is only stepped by the host in between frames (deterministic simulations, replay harnesses, custom get_time on a virtualized timeline), ecs_progress() blocks forever as soon as a target FPS is set. World_progress_w_stalled_clock_w_target_fps in this PR hangs on current master (and on #2247 alone, which fixes the measurement half only). A clock too coarse to observe an individual sleep does exit, but only by spinning through many sleep and measure calls per clock tick.

Fix

The contract this PR implements (now stated in the ecs_set_target_fps docs): get_time and sleep must agree about the passage of time. That is deliberately a coherence requirement rather than an assumption that the clock tracks wall time: both functions may run on a virtualized timeline of any speed and pacing still works, because the keeping-up test compares clock advance against the interval just slept rather than against wall time; an application that replaces one of the two must replace the other consistently. Partial disagreement degrades gracefully instead of blocking, in two bands. A clock that observes at least a quarter of each interval slept is classified as keeping up and reaches the target, to within the half interval the loop stops at, and pays the disagreement in blocking time: covering a frame period of clock time at a quarter speed costs four periods of real sleep, and the quarter threshold is what bounds that. Below the threshold the clock is classified as not keeping up and the stall budget ends the frame. The quarter-boundary tests pin both bands (17/64 of each sleep observed reaches the target and asks for 3.6 periods of sleep; 15/64 stops at 62% of the target with the budget spent).

Mechanically:

• The clock counts as keeping up when it advances by at least a quarter of the interval just slept. Requiring only "any advance" is not enough: a clock that ticks a nanosecond per read would count as keeping up on every iteration while making no progress toward the target.
• When the clock is not keeping up, the sleep interval escalates (doubles). On a coarse clock the interval eventually crosses a clock tick, so pacing keeps working at reduced granularity. When the clock catches up, the interval resets, since leaving it escalated overshoots the target for the rest of the frame.
• A stall budget of one frame period, which never refills within a frame, terminates the frame against a clock that never keeps up. It deliberately never refills: a budget that resets whenever the clock advances a little lets clock jitter replay the escalation chain indefinitely, when the interval clamp near the budget boundary gets small enough for jitter to register as keeping up. The dither-clock tests pin this by bounding total requested sleep per frame.
• Behind the budget is a ceiling on the number of times one frame may sleep, which no clock reaches. An interval that keeps up advances the measured delta by a quarter of itself while the exit condition needs only eight initial intervals of advance, and an interval that does not keep up is charged to the budget, so both branches are bounded independently of what the clock does. Giving a model of the clock complete freedom to answer each read with whichever value prolongs the loop, and searching that game tree exhaustively, the worst case is 36 iterations and 4.75 frame periods of requested sleep, or 41 iterations if the clock may also run backwards. The ceiling is 128.

Argument validation

ecs_set_target_fps now rejects targets that are not zero or within 1e-9 to 1e9. The frame time is the reciprocal of the target, so a subnormal target yields an infinite frame time and sleep interval, and the value can arrive from outside the application through the REST world summary endpoint. A range check rather than a classification macro keeps the frame time finite and within [1e-9, 1e9] by construction, rejects NaN and infinity, and compiles for any type ecs_ftime_t is defined to, including the integer configuration in the custom build tests. In release builds the check compiles out and is backstopped by ecs_sleepf, which now refuses durations it cannot convert to the seconds and nanoseconds the OS sleep API takes: converting a value of 2^31 seconds or more to int is undefined behavior, and the same comparison rejects NaN. A refused sleep returns immediately, is measured as the clock not keeping up, and rate limiting is skipped for that frame instead of waiting.

Tests

Fourteen new tests: stalled clock with target FPS (real and no-op sleep, with bounds on how much sleep may be requested); pacing accuracy against a sleep-driven simulated clock at three work levels, deterministic to microseconds since the fake sleep advances the fake clock by exactly the requested interval; time conservation on a coarse clock with target FPS, including clock read-count bounds that fail if escalation is removed or pacing gives up on the first stall; clocks advancing just above and just below the keeping-up fraction, which pin the quarter constant and both bands of the contract; dither and host-stepped clocks bounding total per-frame sleep; abort tests for the fps checks; and a test that ecs_sleepf never forwards an unrepresentable duration to the OS sleep.

Verified with the full test/core and test/addons suites on Linux, in debug and sanitize builds. The new clock and pacing tests also pass on Windows/MSVC; since the fake clock and fake sleep drive all timing, they are deterministic across platforms. distr/ regenerated from a clean tree.

🤖 Generated with Claude Code