Fix ecs_progress blocking when the clock does not advance between frames

Frame time measurement retried in a loop until the clock returned a
nonzero delta. On a clock that is too coarse to measure a short frame
(a browser with reduced timer precision, a coarse OS tick), every frame
that finishes within one clock quantum busy-spins reading the clock
until the quantum passes. On a clock that only advances when the host
steps it in between frames (emscripten without asyncify, simulated
clocks) the loop never exits and ecs_progress blocks forever.

A zero measurement now reports a minimal nonzero delta
(ECS_FRAME_MIN_DELTA_TIME) rather than measuring again until the clock
moves. Because the frame start time is written back value-identical when
the clock did not advance, the elapsed time is credited in full to the
frame in which the clock next advances, so no time is lost or invented
beyond the reported minimum. Reporting a nonzero delta also keeps every
existing divisor of delta_time safe. A delta of zero is already
observable today (time_scale 0, OnStart systems), so this changes no
contract for consumers. The first frame that reports the minimum logs a
warning, once per world, so a rate that was computed by dividing by it
can be traced to the clock rather than debugged as a spike.

The first-frame branch is now selected by a world flag instead of
testing the frame start time against zero, which pinned a simulated
clock that starts at 0 to the first-frame branch forever.

The world summary computed fps as 1.0 / delta_time_raw, which is inf
before the first measured frame (not representable in JSON on the REST
endpoint) and a rate in the billions on frames where the clock did not
advance. It now reports 0 when no measurable frame time exists, and the
windowed fps gauge in the stats addon applies the same threshold: a
stats window averaging at or below the minimum delta reports 0 instead
of the reciprocal of the minimum.

Tests cover a stalled clock, a stalled clock that reads 0, the warning
firing exactly once across repeated stalled frames, and a coarse clock,
including that measured deltas add up to how far the clock actually
moved; the stalled clock stats test pins the summary and the gauge
together.

Note: with a target FPS configured a stalled clock still blocks, in the
frame rate limiting loop of flecs_insert_sleep. That is a separate
defect with its own fix and tests, submitted as a follow-up PR.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: Simon

distr/flecs.c

@@ -4133,6 +4133,13 @@ void flecs_wait_for_sync(
 /* Used in id records to keep track of entities used with id flags */
 extern const ecs_entity_t EcsFlag;
 
+/* Smallest delta time reported for a frame. Reported instead of zero when the
+ * clock did not advance in between two measurements; consumers that derive a
+ * rate from the frame delta test against it to tell a stalled frame apart from
+ * a very short one. Rounds to zero (disabling both) if ecs_ftime_t is redefined
+ * to an integer or fixed point type. */
+#define ECS_FRAME_MIN_DELTA_TIME ((ecs_ftime_t)1e-9)
+
 ////////////////////////////////////////////////////////////////////////////////
 //// Bootstrap API
 ////////////////////////////////////////////////////////////////////////////////
@@ -24397,28 +24404,41 @@ static ecs_ftime_t flecs_start_measure_frame(
         (ECS_EQZERO(user_delta_time)))
     {
         ecs_time_t t = world->frame_start_time;
-        do {
-            if (world->frame_start_time.nanosec || world->frame_start_time.sec){
-                delta_time = flecs_insert_sleep(world, &t);
-            } else {
-                ecs_time_measure(&t);
-                if (ECS_NEQZERO(world->info.target_fps)) {
-                    delta_time = (ecs_ftime_t)1.0 / world->info.target_fps;
-                } else {
-                    /* Best guess */
-                    delta_time = (ecs_ftime_t)1.0 / (ecs_ftime_t)60.0;
 
-                    if (ECS_EQZERO(delta_time)) {
-                        delta_time = user_delta_time;
-                        break;
-                    }
-                }
+        /* A simulated clock can legitimately start at 0, so the frame start
+         * time itself can't tell whether a previous frame measured one. */
+        if (world->flags & EcsWorldFrameStartTimeSet) {
+            delta_time = flecs_insert_sleep(world, &t);
+        } else {
+            ecs_time_measure(&t);
+            if (ECS_NEQZERO(world->info.target_fps)) {
+                delta_time = (ecs_ftime_t)1.0 / world->info.target_fps;
+            } else {
+                /* Best guess */
+                delta_time = (ecs_ftime_t)1.0 / (ecs_ftime_t)60.0;
             }
+        }
 
-        /* Keep trying while delta_time is zero */
-        } while (ECS_EQZERO(delta_time));
+        if (delta_time < ECS_FRAME_MIN_DELTA_TIME) {
+            /* A coarse or host-stepped clock can legitimately return the same
+             * instant twice. Report the smallest nonzero delta rather than
+             * measure again until the clock moves, which never returns on a
+             * host-stepped clock. The frame start time is unchanged, so the
+             * elapsed time is credited in full to the frame in which the
+             * clock next advances. */
+            delta_time = ECS_FRAME_MIN_DELTA_TIME;
+
+            /* Once per world, so a rate computed by dividing by the minimum
+             * can be traced to this rather than debugged as a spike. */
+            if (!(world->flags & EcsWorldFrameMinDeltaWarned)) {
+                world->flags |= EcsWorldFrameMinDeltaWarned;
+                ecs_warn("clock did not advance between frames, "
+                    "reporting minimal delta time");
+            }
+        }
 
         world->frame_start_time = t;
+        world->flags |= EcsWorldFrameStartTimeSet;
 
         /* Keep track of total time passed in world */
         world->info.world_time_total_raw += (double)delta_time;
@@ -79607,8 +79627,15 @@ void ecs_world_stats_get(
     ECS_COUNTER_RECORD(&s->performance.merge_time, t, world->info.merge_time_total);
     ECS_COUNTER_RECORD(&s->performance.rematch_time, t, world->info.rematch_time_total);
     ECS_GAUGE_RECORD(&s->performance.delta_time, t, delta_world_time);
-    if (ECS_NEQZERO(delta_world_time) && ECS_NEQZERO(delta_frame_count)) {
-        ECS_GAUGE_RECORD(&s->performance.fps, t, (double)1 / (delta_world_time / (double)delta_frame_count));
+    double avg_frame_time = 0;
+    if (ECS_NEQZERO(delta_frame_count)) {
+        avg_frame_time = delta_world_time / delta_frame_count;
+    }
+
+    /* Frames whose clock did not advance report the minimum delta, which is
+     * not a measurable frame rate. Report 0, like the world summary. */
+    if (avg_frame_time > (double)ECS_FRAME_MIN_DELTA_TIME) {
+        ECS_GAUGE_RECORD(&s->performance.fps, t, (double)1 / avg_frame_time);
     } else {
         ECS_GAUGE_RECORD(&s->performance.fps, t, 0);
     }
@@ -80324,7 +80351,12 @@ static void flecs_copy_world_summary(
 
     dst->target_fps = (double)info->target_fps;
     dst->time_scale = (double)info->time_scale;
-    dst->fps = 1.0 / (double)info->delta_time_raw;
+    /* A delta at or below the reported minimum means no frame has run yet,
+     * the clock did not advance, or the application passed a degenerate
+     * delta. None of those is a meaningful rate, so report zero. */
+    dst->fps = (info->delta_time_raw > ECS_FRAME_MIN_DELTA_TIME)
+        ? 1.0 / (double)info->delta_time_raw
+        : 0.0;
 
     dst->frame_time_frame = (double)info->frame_time_total - dst->frame_time_total;
     dst->system_time_frame = (double)info->system_time_total - dst->system_time_total;

distr/flecs.h

@@ -648,6 +648,8 @@ extern "C" {
 #define EcsWorldMeasureSystemTime     (1u << 6)
 #define EcsWorldMultiThreaded         (1u << 7)
 #define EcsWorldFrameInProgress       (1u << 8)
+#define EcsWorldFrameStartTimeSet     (1u << 9)
+#define EcsWorldFrameMinDeltaWarned   (1u << 10)
 
 ////////////////////////////////////////////////////////////////////////////////
 //// OS API flags
@@ -13070,6 +13072,13 @@ extern "C" {
  *
  * This function should only be run from the main thread.
  *
+ * When the clock does not advance in between two measurements, a minimal
+ * nonzero delta time is returned instead of blocking until it does. The time
+ * that was not reported is credited to the frame in which the clock next
+ * advances. The first such frame logs a warning. Code that derives a rate by
+ * dividing by the delta time should treat a delta at or below 1e-9 as a frame
+ * in which no time could be measured, rather than as a rate.
+ *
  * @param world The world.
  * @param delta_time Time elapsed since the last frame.
  * @return The provided delta_time, or measured time if 0 was provided.

distr/flecs_no_addons.c

@@ -2598,6 +2598,13 @@ bool flecs_component_is_delete_locked(
 /* Used in id records to keep track of entities used with id flags */
 extern const ecs_entity_t EcsFlag;
 
+/* Smallest delta time reported for a frame. Reported instead of zero when the
+ * clock did not advance in between two measurements; consumers that derive a
+ * rate from the frame delta test against it to tell a stalled frame apart from
+ * a very short one. Rounds to zero (disabling both) if ecs_ftime_t is redefined
+ * to an integer or fixed point type. */
+#define ECS_FRAME_MIN_DELTA_TIME ((ecs_ftime_t)1e-9)
+
 ////////////////////////////////////////////////////////////////////////////////
 //// Bootstrap API
 ////////////////////////////////////////////////////////////////////////////////

distr/flecs_no_addons.h

@@ -468,6 +468,8 @@ extern "C" {
 #define EcsWorldMeasureSystemTime     (1u << 6)
 #define EcsWorldMultiThreaded         (1u << 7)
 #define EcsWorldFrameInProgress       (1u << 8)
+#define EcsWorldFrameStartTimeSet     (1u << 9)
+#define EcsWorldFrameMinDeltaWarned   (1u << 10)
 
 ////////////////////////////////////////////////////////////////////////////////
 //// OS API flags

include/flecs/addons/frame.h

@@ -38,6 +38,13 @@ extern "C" {
  *
  * This function should only be run from the main thread.
  *
+ * When the clock does not advance in between two measurements, a minimal
+ * nonzero delta time is returned instead of blocking until it does. The time
+ * that was not reported is credited to the frame in which the clock next
+ * advances. The first such frame logs a warning. Code that derives a rate by
+ * dividing by the delta time should treat a delta at or below 1e-9 as a frame
+ * in which no time could be measured, rather than as a rate.
+ *
  * @param world The world.
  * @param delta_time Time elapsed since the last frame.
  * @return The provided delta_time, or measured time if 0 was provided.

include/flecs/private/api_flags.h

@@ -24,6 +24,8 @@ extern "C" {
 #define EcsWorldMeasureSystemTime     (1u << 6)
 #define EcsWorldMultiThreaded         (1u << 7)
 #define EcsWorldFrameInProgress       (1u << 8)
+#define EcsWorldFrameStartTimeSet     (1u << 9)
+#define EcsWorldFrameMinDeltaWarned   (1u << 10)
 
 ////////////////////////////////////////////////////////////////////////////////
 //// OS API flags

src/addons/frame.c

@@ -67,28 +67,41 @@ static ecs_ftime_t flecs_start_measure_frame(
         (ECS_EQZERO(user_delta_time)))
     {
         ecs_time_t t = world->frame_start_time;
-        do {
-            if (world->frame_start_time.nanosec || world->frame_start_time.sec){
-                delta_time = flecs_insert_sleep(world, &t);
+
+        /* A simulated clock can legitimately start at 0, so the frame start
+         * time itself can't tell whether a previous frame measured one. */
+        if (world->flags & EcsWorldFrameStartTimeSet) {
+            delta_time = flecs_insert_sleep(world, &t);
+        } else {
+            ecs_time_measure(&t);
+            if (ECS_NEQZERO(world->info.target_fps)) {
+                delta_time = (ecs_ftime_t)1.0 / world->info.target_fps;
             } else {
-                ecs_time_measure(&t);
-                if (ECS_NEQZERO(world->info.target_fps)) {
-                    delta_time = (ecs_ftime_t)1.0 / world->info.target_fps;
-                } else {
-                    /* Best guess */
-                    delta_time = (ecs_ftime_t)1.0 / (ecs_ftime_t)60.0;
-
-                    if (ECS_EQZERO(delta_time)) {
-                        delta_time = user_delta_time;
-                        break;
-                    }
-                }
+                /* Best guess */
+                delta_time = (ecs_ftime_t)1.0 / (ecs_ftime_t)60.0;
             }
-
-        /* Keep trying while delta_time is zero */
-        } while (ECS_EQZERO(delta_time));
+        }
+
+        if (delta_time < ECS_FRAME_MIN_DELTA_TIME) {
+            /* A coarse or host-stepped clock can legitimately return the same
+             * instant twice. Report the smallest nonzero delta rather than
+             * measure again until the clock moves, which never returns on a
+             * host-stepped clock. The frame start time is unchanged, so the
+             * elapsed time is credited in full to the frame in which the
+             * clock next advances. */
+            delta_time = ECS_FRAME_MIN_DELTA_TIME;
+
+            /* Once per world, so a rate computed by dividing by the minimum
+             * can be traced to this rather than debugged as a spike. */
+            if (!(world->flags & EcsWorldFrameMinDeltaWarned)) {
+                world->flags |= EcsWorldFrameMinDeltaWarned;
+                ecs_warn("clock did not advance between frames, "
+                    "reporting minimal delta time");
+            }
+        }
 
         world->frame_start_time = t;
+        world->flags |= EcsWorldFrameStartTimeSet;
 
         /* Keep track of total time passed in world */
         world->info.world_time_total_raw += (double)delta_time;

src/addons/stats/stats.c

@@ -256,8 +256,15 @@ void ecs_world_stats_get(
     ECS_COUNTER_RECORD(&s->performance.merge_time, t, world->info.merge_time_total);
     ECS_COUNTER_RECORD(&s->performance.rematch_time, t, world->info.rematch_time_total);
     ECS_GAUGE_RECORD(&s->performance.delta_time, t, delta_world_time);
-    if (ECS_NEQZERO(delta_world_time) && ECS_NEQZERO(delta_frame_count)) {
-        ECS_GAUGE_RECORD(&s->performance.fps, t, (double)1 / (delta_world_time / (double)delta_frame_count));
+    double avg_frame_time = 0;
+    if (ECS_NEQZERO(delta_frame_count)) {
+        avg_frame_time = delta_world_time / delta_frame_count;
+    }
+
+    /* Frames whose clock did not advance report the minimum delta, which is
+     * not a measurable frame rate. Report 0, like the world summary. */
+    if (avg_frame_time > (double)ECS_FRAME_MIN_DELTA_TIME) {
+        ECS_GAUGE_RECORD(&s->performance.fps, t, (double)1 / avg_frame_time);
     } else {
         ECS_GAUGE_RECORD(&s->performance.fps, t, 0);
     }

src/addons/stats/world_summary.c

@@ -20,7 +20,12 @@ static void flecs_copy_world_summary(
 
     dst->target_fps = (double)info->target_fps;
     dst->time_scale = (double)info->time_scale;
-    dst->fps = 1.0 / (double)info->delta_time_raw;
+    /* A delta at or below the reported minimum means no frame has run yet,
+     * the clock did not advance, or the application passed a degenerate
+     * delta. None of those is a meaningful rate, so report zero. */
+    dst->fps = (info->delta_time_raw > ECS_FRAME_MIN_DELTA_TIME)
+        ? 1.0 / (double)info->delta_time_raw
+        : 0.0;
 
     dst->frame_time_frame = (double)info->frame_time_total - dst->frame_time_total;
     dst->system_time_frame = (double)info->system_time_total - dst->system_time_total;

src/private_api.h

@@ -56,6 +56,13 @@
 /* Used in id records to keep track of entities used with id flags */
 extern const ecs_entity_t EcsFlag;
 
+/* Smallest delta time reported for a frame. Reported instead of zero when the
+ * clock did not advance in between two measurements; consumers that derive a
+ * rate from the frame delta test against it to tell a stalled frame apart from
+ * a very short one. Rounds to zero (disabling both) if ecs_ftime_t is redefined
+ * to an integer or fixed point type. */
+#define ECS_FRAME_MIN_DELTA_TIME ((ecs_ftime_t)1e-9)
+
 ////////////////////////////////////////////////////////////////////////////////
 //// Bootstrap API
 ////////////////////////////////////////////////////////////////////////////////