Document the owning-loop cursor-cascade cost on force_close_transport

When AsyncConnection.force_close_transport is invoked from a
coroutine on the owning loop with many open cursors, the cursor-
cascade walk runs inline — synchronous attribute writes plus a
weakref.proxy swap per cursor. For a connection with hundreds of
open cursors that's measurable loop CPU before the method returns.

The documented intent of the method is loop-already-dead / GC /
atexit / SA-do_terminate paths where the cascade-on-owning-loop
case does not arise, so the behaviour is correct. Surface the
constraint in the docstring so an in-loop caller with many open
cursors picks the cooperative close() instead.

Add a docstring-lint test that pins the wording so a future
refactor cannot silently drop the constraint.

Author: antoineleclair

src/dqlitedbapi/aio/connection.py

@@ -1192,6 +1192,18 @@ def force_close_transport(self) -> None:
         runs directly; on a foreign thread with a live loop the cancel
         is scheduled via ``call_soon_threadsafe`` so the ready-queue
         is not mutated cross-thread.
+
+        Owning-loop note: when invoked from a coroutine on the
+        owning loop (e.g. an in-loop test fixture explicitly
+        terminating a connection with many open cursors), the
+        cursor-cascade walk runs inline without yielding — synchronous
+        attribute writes on each cursor plus a ``weakref.proxy`` swap.
+        For a connection with N open cursors that is O(N) loop CPU
+        before this method returns. Documented intent is the
+        loop-already-dead / GC / atexit / SA-do_terminate paths where
+        the cascade-on-owning-loop case does not arise; an in-loop
+        caller with hundreds of open cursors who wants cooperative
+        teardown should await ``close()`` instead.
         """
         # PEP 249 §6.4 + project discipline: every public Connection
         # method clears ``messages`` as the first statement.

tests/test_force_close_transport_docstring_owning_loop_note.py

@@ -0,0 +1,34 @@
+"""Pin: ``AsyncConnection.force_close_transport``'s docstring
+documents the owning-loop cursor-cascade cost.
+
+When invoked from a coroutine on the owning loop, the cursor-cascade
+walk runs inline (no yield) — synchronous per-cursor attribute writes
+plus a ``weakref.proxy`` swap. For a connection with hundreds of
+open cursors that's measurable loop CPU. The documented intent of
+the method is loop-already-dead / GC / atexit / SA-do_terminate
+paths where the cascade-on-owning-loop case doesn't arise, so the
+behaviour is correct; the docstring just needs to surface the
+constraint so an in-loop caller can pick the right method (``close()``).
+"""
+
+from __future__ import annotations
+
+from dqlitedbapi.aio.connection import AsyncConnection
+
+
+def test_force_close_transport_docstring_mentions_owning_loop_cascade() -> None:
+    """The docstring must surface the owning-loop O(N_cursors)
+    cascade cost so an in-loop caller picks ``close()`` instead."""
+    doc = AsyncConnection.force_close_transport.__doc__ or ""
+    assert "owning loop" in doc.lower(), (
+        "force_close_transport docstring must mention the owning-loop "
+        "case so in-loop callers can pick the cooperative ``close()``"
+    )
+    assert "cursor" in doc.lower(), (
+        "force_close_transport docstring must mention cursor-cascade "
+        "cost on the owning-loop call shape"
+    )
+    assert "close()" in doc, (
+        "force_close_transport docstring must point at ``close()`` "
+        "as the cooperative alternative for in-loop callers"
+    )