Feat/coroutine pool

[mahimairaja]

Summary by CodeRabbit

Release Notes

• Documentation

  • Added new benchmark results dated 2026-05-05 confirming Phase 1 gate continues to pass.

• Tests

  • Enhanced benchmark observability with scheduler latency metrics (median, p99, max).
  • Added hardware fingerprinting (CPU, RAM, kernel, Python version) to results.
  • Implemented diagnostic notes tracking in benchmark output.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 220939c8-2324-4ca0-bd06-96c584e571cb

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/coroutine-pool

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[coderabbitai]

🧹 Nitpick comments (2)

tests/benchmarks/density.py (2)

69-71: ⚡ Quick win

Replace loose metrics dictionaries with typed dataclasses.

scheduler_latency_ms: dict[str, float] and hardware: dict[str, Any] lose schema guarantees and force awkward typing (for example, "samples" is a count but stored as float). Use typed dataclasses (or typed models) for these payloads.

Suggested direction

+@dataclass(frozen=True)
+class SchedulerLatencyStats:
+    samples: int
+    median_ms: float
+    p99_ms: float
+    max_ms: float
+
+@dataclass(frozen=True)
+class HardwareFingerprint:
+    cpu_model: str
+    cpu_count: int | None
+    total_ram_gb: float | None
+    kernel: str
+    python_version: str
@@
-    scheduler_latency_ms: dict[str, float] = field(default_factory=dict)
-    hardware: dict[str, Any] = field(default_factory=dict)
+    scheduler_latency_ms: SchedulerLatencyStats | None = None
+    hardware: HardwareFingerprint | None = None

As per coding guidelines, "Prefer dataclass or clear typed classes over loose dictionaries for structured data" and "Prefer concrete types over Any in Python type hints."

Also applies to: 236-245

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/benchmarks/density.py` around lines 69 - 71, Replace the loose dicts by
defining explicit dataclasses for the scheduler latency payload and the hardware
payload, then change the fields scheduler_latency_ms and hardware on the
enclosing dataclass to use those concrete types (with default_factory for each
dataclass) instead of dict[str, float] and dict[str, Any]; ensure the scheduler
dataclass uses proper numeric types for counts (e.g., int for "samples") and
floats for times, and the hardware dataclass types each field explicitly (no
Any), update any code constructing or accessing scheduler_latency_ms and
hardware to use the new attribute names/types on the dataclass (e.g.,
MySchedulerLatency and MyHardware classes referenced where scheduler_latency_ms
and hardware were used), and apply the same replacement for the other occurrence
noted around the second block.

---

162-163: ⚡ Quick win

Replace suppress(CancelledError) with explicit stop-event timeout waits.

The latency sampler suppresses CancelledError, which weakens shutdown semantics and can mask unexpected cancellations. Use asyncio.wait_for(stop.wait(), timeout=...) with suppress(TimeoutError) instead, matching the pattern already used in _sample_loop_rss in the same file. This respects the stop signal immediately without swallowing exceptions.

Suggested patch

 async def _sample_loop_latency(stop: asyncio.Event, samples: list[float]) -> None:
     """Background task: measure scheduler wakeup latency in milliseconds.
 
     A small ``asyncio.sleep`` is requested every interval; the delta between
     the requested wakeup time and the actual return time is the loop's
     scheduling latency. Under heavy task pressure this rises and signals
     starvation of the event loop.
     """
     while not stop.is_set():
         target = time.monotonic() + _LATENCY_SAMPLE_INTERVAL_SECONDS
-        with contextlib.suppress(asyncio.CancelledError):
-            await asyncio.sleep(_LATENCY_SAMPLE_INTERVAL_SECONDS)
+        try:
+            await asyncio.wait_for(stop.wait(), timeout=_LATENCY_SAMPLE_INTERVAL_SECONDS)
+        except TimeoutError:
+            pass
+        if stop.is_set():
+            break
         actual = time.monotonic()
         samples.append(max(0.0, (actual - target) * 1000.0))

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/benchmarks/density.py` around lines 162 - 163, Replace the current
"with contextlib.suppress(asyncio.CancelledError): await
asyncio.sleep(_LATENCY_SAMPLE_INTERVAL_SECONDS)" in the latency sampling loop
with an explicit wait on the stop event: use "await
asyncio.wait_for(stop.wait(), timeout=_LATENCY_SAMPLE_INTERVAL_SECONDS)" and
wrap that in "contextlib.suppress(asyncio.TimeoutError)" (mirroring
_sample_loop_rss) so the loop respects immediate stop signals instead of
swallowing CancelledError; keep the existing _LATENCY_SAMPLE_INTERVAL_SECONDS
and stop symbols to locate the change.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@tests/benchmarks/density.py`:
- Around line 69-71: Replace the loose dicts by defining explicit dataclasses
for the scheduler latency payload and the hardware payload, then change the
fields scheduler_latency_ms and hardware on the enclosing dataclass to use those
concrete types (with default_factory for each dataclass) instead of dict[str,
float] and dict[str, Any]; ensure the scheduler dataclass uses proper numeric
types for counts (e.g., int for "samples") and floats for times, and the
hardware dataclass types each field explicitly (no Any), update any code
constructing or accessing scheduler_latency_ms and hardware to use the new
attribute names/types on the dataclass (e.g., MySchedulerLatency and MyHardware
classes referenced where scheduler_latency_ms and hardware were used), and apply
the same replacement for the other occurrence noted around the second block.
- Around line 162-163: Replace the current "with
contextlib.suppress(asyncio.CancelledError): await
asyncio.sleep(_LATENCY_SAMPLE_INTERVAL_SECONDS)" in the latency sampling loop
with an explicit wait on the stop event: use "await
asyncio.wait_for(stop.wait(), timeout=_LATENCY_SAMPLE_INTERVAL_SECONDS)" and
wrap that in "contextlib.suppress(asyncio.TimeoutError)" (mirroring
_sample_loop_rss) so the loop respects immediate stop signals instead of
swallowing CancelledError; keep the existing _LATENCY_SAMPLE_INTERVAL_SECONDS
and stop symbols to locate the change.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 110e5ee4-fc2d-44f8-9b36-19aa5a23a102

📥 Commits

Reviewing files that changed from the base of the PR and between b576dbb and 1d87413.

📒 Files selected for processing (2)

• docs/benchmarks/density-v0.1.md
• tests/benchmarks/density.py