From ca6ede33e1b62a9d309058e7391e436fc5e196f9 Mon Sep 17 00:00:00 2001 From: ethernet Date: Tue, 14 Jul 2026 15:44:55 -0400 Subject: [PATCH] docs(docker-tests): document why poll loop beats blocking exec in wait_for_container_ready Tried replacing the N-times-docker-exec polling loop with a single blocking docker exec (in-container until/sleep loop). CI profiling showed this was a net regression: docker exec connection overhead on shared runners is ~0.7-1s per call, while the existing poll approach uses 3-7 quick 0.27s execs. The blocking approach traded fewer calls for longer per-call duration and lost. Reverted to the original poll loop, added a docstring note explaining why so the next person does not re-attempt the same optimization. --- tests/docker/conftest.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/tests/docker/conftest.py b/tests/docker/conftest.py index ab841f78e32..18e1f7bc2c2 100644 --- a/tests/docker/conftest.py +++ b/tests/docker/conftest.py @@ -195,6 +195,14 @@ def wait_for_container_ready( Raises ``TimeoutError`` if the container never becomes ready — much better than a fixed ``time.sleep()`` that either wastes time on fast machines or flakes on slow ones. + + Note: an earlier iteration tried a single blocking ``docker exec`` + with an in-container ``until`` loop to eliminate polling overhead. + That was a net regression on CI: the per-``docker exec`` connection + overhead on shared runners (~0.7–1s) is higher than the cost of + 3–7 quick poll calls (0.27s each), so the blocking approach traded + fewer calls for longer per-call duration and lost. The poll loop + is kept because it's better suited to CI's docker exec cost profile. """ end = time.monotonic() + deadline_s while time.monotonic() < end: