test(perf): guard import laziness and parallel coordinator scaling

Author: wolph

tests/test_perf_budget.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
+import concurrent.futures
 import io
+import subprocess
 import sys
 import timeit
 
@@ -82,3 +84,74 @@ def test_iterator_overhead_budget() -> None:
         f'({clock_ns:.1f} ns) - likely a regression to per-iteration '
         f'clock reads'
     )
+
+
+def test_import_stays_lazy() -> None:
+    # Deterministic, not timing-based: `import progressbar` must load
+    # nothing beyond the package itself and the version module. Anything
+    # else appearing here means an eager import crept into __init__.py
+    # and the ~1.6 ms import time regressed for every consumer.
+    out: str = subprocess.run(
+        [
+            sys.executable,
+            '-c',
+            'import sys, progressbar; '
+            "print(','.join(sorted("
+            "m for m in sys.modules if m.startswith('progressbar'))))",
+        ],
+        capture_output=True,
+        text=True,
+        check=True,
+    ).stdout.strip()
+    assert out == 'progressbar,progressbar.__about__', (
+        f'import progressbar eagerly loaded: {out}'
+    )
+
+
+def _noop(value: int) -> int:
+    return value
+
+
+def _parallel_map_us_per_item(n: int) -> float:
+    """Per-item wall cost of `progressbar.map` on a shared thread pool.
+
+    The executor is created outside the measurement, so this isolates
+    the coordinator itself: chunking, submission windowing, the
+    done-queue and result assembly.
+    """
+    import progressbar
+
+    with concurrent.futures.ThreadPoolExecutor(4) as executor:
+        # Warm-up so pool spin-up and lazy imports land outside timing.
+        progressbar.map(_noop, range(64), pool=executor, bar=False)
+        elapsed: float = min(
+            timeit.timeit(
+                lambda: progressbar.map(
+                    _noop, range(n), pool=executor, bar=False
+                ),
+                number=1,
+            )
+            for _ in range(3)
+        )
+    return elapsed / n * 1e6
+
+
+@pytest.mark.no_freezegun
+def test_parallel_map_overhead_scales_linearly() -> None:
+    # Measure both before any early return so every line runs under
+    # coverage (same pattern as the iterator budget above).
+    small: float = _parallel_map_us_per_item(1_000)
+    large: float = _parallel_map_us_per_item(10_000)
+    if _coverage_active():
+        return
+    # Machine-independent guard for the done-queue design: per-item cost
+    # must stay flat as the batch grows. The rejected coordinator design
+    # (re-registering a waiter on every pending future each poll) scales
+    # with batch size and blows past this immediately at 10x the items.
+    # A 3x ceiling tolerates noisy runners without letting an O(n) tick
+    # regime back in.
+    assert large < 3 * small, (
+        f'parallel map per-item cost grew from {small:.2f} us at 1k items '
+        f'to {large:.2f} us at 10k items - the coordinator is no longer '
+        f'O(1) per completion'
+    )