Sync display_driver.py from lvgl-bindings 45be184 (#24)

lvgl-bindings#19: after a slow LVGL pass, the frame gate holds for at most
max_yield_ms (default 100; event_loop(max_yield_ms=...) or on the
instance). Passes up to 100 ms hold exactly as before, so lvgl-bindings#15's
case is unchanged; a long pass -- typically application work run from LVGL
timers -- no longer leaves the thread idle for as long again.

It also brings d5f3d34 (lvgl-bindings#15), which this repo's pin predated: after a slow pass the gate holds for as long as the pass took, so a slow frame lowers the frame rate instead of taking the application's thread.

Made with scripts/sync_from_lvgl_bindings.sh --ref 45be1848ed73057891aff7ccd477ce563a56939a.

Author: bdbarnett

LVGL_BINDINGS_COMMIT

@@ -1 +1 @@
-aa6c6bc449aed6936b644ab45b11e453945a18ee
+45be1848ed73057891aff7ccd477ce563a56939a

display_driver.py

@@ -563,6 +563,9 @@ class event_loop:
 
     _current_instance = None
 
+    # The most the gate holds LVGL back after a slow pass (see _arm_gate).
+    max_yield_ms = 100
+
     def __init__(
         self,
         freq=None,
@@ -571,6 +574,7 @@ def __init__(
         asynchronous=False,
         exception_sink=None,
         period_ms=None,
+        max_yield_ms=None,
     ):
         """Create and register the LVGL event loop.
 
@@ -583,6 +587,9 @@ def __init__(
             exception_sink: Callable receiving exceptions from task handling;
                 defaults to :meth:`default_exception_sink`.
             period_ms: Explicit tick period in milliseconds (overrides ``freq``).
+            max_yield_ms: Most the gate stays shut after a slow pass, leaving
+                the thread to the application (default 100; see
+                :meth:`_arm_gate`).
 
         Raises:
             RuntimeError: Another loop is already running or async mode is
@@ -602,6 +609,8 @@ def __init__(
             self.delay = max(1, 1000 // int(freq))
         else:
             self.delay = LVGL_PERIOD_MS
+        if max_yield_ms is not None:
+            self.max_yield_ms = int(max_yield_ms)
 
         self.refresh_cb = refresh_cb
         self.exception_sink = exception_sink if exception_sink else self.default_exception_sink
@@ -708,7 +717,7 @@ def _gate_allows(self):
         # Positive diff means _next_ok_ms is still in the future.
         return ticks_diff(self._next_ok_ms, ticks_ms()) <= 0
 
-    def _arm_gate(self):
+    def _arm_gate(self, work_ms=0):
         """Open the next slot one period after the last one, not after the work.
 
         Pacing from *completion* silently halved the tick rate: the next timer
@@ -717,10 +726,31 @@ def _arm_gate(self):
         second tick was rejected no matter how fast the work was (measured 50/s
         on a 10 ms timer, ESP32-P4).
 
-        Advancing from the previous slot keeps the cadence for fast frames. The
-        backlog protection the old comment was after is still there: if a slow
-        flush overran its slot, resynchronise to now instead of letting the
-        queued ticks fire back-to-back to catch up.
+        Advancing from the previous slot keeps the cadence for fast frames.
+
+        The overrun branch is what decides how much of the thread the
+        application gets, because on MicroPython the tick arrives through
+        ``micropython.schedule`` and so runs between the application's own
+        bytecodes. Resynchronising to *now* opened the gate at the instant the
+        slow pass ended, leaving only the one tick period before the next one
+        started: a 67.8 ms repaint against a 10 ms tick took ~87 % of the
+        thread indefinitely, and a 300-iteration Python loop took 20 340 ms
+        (lvgl-bindings#15). So after an overrun the gate stays shut for as
+        long as the pass itself took -- a slow frame halves the frame rate
+        instead of taking the thread. ``now + delay`` is not enough: the
+        timer's own cadence already delivers the next tick a period later,
+        which is exactly the sliver the application was already getting.
+
+        Fast frames never reach this branch, so their cadence is untouched.
+
+        The hold is capped at ``max_yield_ms``. A pass much longer than a
+        repaint is almost always the application's own work, run from LVGL
+        timers (list rows built, results drained), and there is no other
+        application code waiting for the thread: an uncapped hold only left
+        it idle for as long again, doubling every UI stall. On an
+        ESP32-S3-Touch-LCD-7 a 440 ms pass was followed by ~400 ms of idle,
+        on every screen change. The capped hold still covers the ~60 ms
+        repaints lvgl-bindings#15 was about.
         """
         if ticks_ms is None or ticks_add is None or ticks_diff is None:
             return
@@ -730,9 +760,20 @@ def _arm_gate(self):
             return
         nxt = ticks_add(self._next_ok_ms, self.delay)
         if ticks_diff(nxt, now) < 0:
-            nxt = now
+            hold = min(work_ms, self.max_yield_ms)
+            nxt = ticks_add(now, self.delay if hold < self.delay else hold)
         self._next_ok_ms = nxt
 
+    def _run_and_arm(self, run):
+        """Run one pass and arm the gate with what that pass cost."""
+        if ticks_ms is None or ticks_diff is None:
+            run()
+            self._arm_gate()
+            return
+        start = ticks_ms()
+        run()
+        self._arm_gate(ticks_diff(ticks_ms(), start))
+
     def timer_cb(self, t):
         """Shared-timer callback: advance LVGL time and run/signal task handling.
 
@@ -761,23 +802,26 @@ def timer_cb(self, t):
             self.refresh_event.set()
             self._arm_gate()
         else:
-            self.task_handler()
-            self._arm_gate()
+            self._run_and_arm(self.task_handler)
 
     async def async_refresh(self):
         """Asyncio task body: wait for refresh signals and run ``lv.task_handler``."""
         while True:
             await self.refresh_event.wait()
             if _LV_NESTING is None or _LV_NESTING.value == 0:
                 self.refresh_event.clear()
+                start = ticks_ms() if ticks_ms is not None else None
                 try:
                     lv.task_handler()
                 except Exception as e:
                     if self.exception_sink:
                         self.exception_sink(e)
                 if self.refresh_cb:
                     self.refresh_cb()
-                self._arm_gate()
+                if start is None:
+                    self._arm_gate()
+                else:
+                    self._arm_gate(ticks_diff(ticks_ms(), start))
 
     def default_exception_sink(self, e):
         """Print ``e`` with traceback to stderr (default :attr:`exception_sink`)."""