noio 0.1__py3-none-any.whl

noio/__init__.py

@@ -0,0 +1,3 @@
+from .routine import routine as routine
+
+__all__ = ["routine"]

noio/_lock.py

@@ -0,0 +1,49 @@
+from types import TracebackType
+from typing import Self
+
+import aiologic
+from aiologic.lowlevel import current_async_library
+
+from .routine import _sync_call
+from .routine import routine
+
+
+class Lock:
+    """An owned, non-reentrant lock shared by threads, greenlets, and async tasks."""
+
+    def __init__(self) -> None:
+        self.__lock = aiologic.Lock()
+
+    @routine
+    async def __enter__(self) -> Self:
+        """Wait for ownership; reacquiring raises RuntimeError."""
+        if _sync_call.get():
+            self.__lock.green_acquire()
+        else:
+            await self.__lock.async_acquire()
+        return self
+
+    @routine
+    async def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Release from the owning thread, greenlet, or async task."""
+        # An ordinary acquisition inside an async function still has green ownership.
+        if self.__lock.green_owned() or current_async_library(failsafe=True) is None:
+            self.__lock.green_release()
+        else:
+            self.__lock.async_release()
+
+    async def __aenter__(self) -> Self:
+        return await self.__enter__.a()
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.__exit__.a(exc_type, exc_value, traceback)

noio/_lock_test.py

@@ -0,0 +1,358 @@
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import AsyncExitStack
+from contextlib import ExitStack
+from threading import Event
+from typing import assert_type
+
+import pytest
+
+from noio import routine
+from noio._lock import Lock
+
+from .conftest import AsyncRuntime
+from .conftest import RunSync
+
+
+def _check_sync(checkpoint: Callable[[], None]) -> None:
+    lock = Lock()
+    with lock as entered:
+        assert assert_type(entered, Lock) is lock
+        with pytest.raises(RuntimeError), lock:
+            pass
+        checkpoint()
+    with pytest.raises(RuntimeError):
+        lock.__exit__(None, None, None)
+
+    error = ValueError("body failed")
+    with pytest.raises(ValueError) as raised, lock as entered:
+        assert assert_type(entered, Lock) is lock
+        raise error
+    assert raised.value is error
+
+    @routine
+    async def inner() -> None:
+        async with lock as entered:
+            assert entered is lock
+            checkpoint()
+            with pytest.raises(RuntimeError, match="Use await function.a"), lock:
+                pass
+            with pytest.raises(RuntimeError, match="Use await function.a"):
+                lock.__exit__(None, None, None)
+
+    @routine
+    async def outer() -> None:
+        await inner.a()
+        async with AsyncExitStack() as stack:
+            assert await stack.enter_async_context(lock) is lock
+
+    outer()
+    with ExitStack() as stack:
+        # Pyright does not bind routine descriptors during protocol matching.
+        assert stack.enter_context(lock) is lock  # pyright: ignore[reportArgumentType]
+        checkpoint()
+
+
+def test_sync_calls(sync_runtime: RunSync) -> None:
+    sync_runtime(_check_sync)
+
+
+def test_thread_contention_and_ownership() -> None:
+    lock = Lock()
+    started = Event()
+    entered = Event()
+
+    @routine
+    async def nested() -> None:
+        async with lock:
+            entered.set()
+
+    def worker() -> None:
+        with pytest.raises(RuntimeError):
+            lock.__exit__(None, None, None)
+        started.set()
+        nested()
+
+    with ThreadPoolExecutor(max_workers=1) as pool:
+        with lock:
+            future = pool.submit(worker)
+            assert started.wait(2)
+            assert not entered.is_set()
+        future.result(timeout=2)
+    assert entered.is_set()
+    with lock:
+        pass
+
+
+def _check_green_contention(checkpoint: Callable[[], None]) -> None:
+    import gevent
+
+    lock = Lock()
+    entered = []
+
+    @routine
+    async def contender() -> None:
+        async with lock:
+            entered.append(True)
+            checkpoint()
+
+    with lock:
+        task = gevent.spawn(contender)
+        checkpoint()
+        assert not entered
+    task.get(timeout=2)
+    assert entered == [True]
+
+    with lock:
+        cancelled = gevent.spawn(contender)
+        checkpoint()
+        cancelled.kill()
+    contender()
+    assert entered == [True, True]
+
+
+@pytest.mark.parametrize(
+    "sync_runtime",
+    ["gevent", "gevent-patched-before-import", "gevent-patched-after-import"],
+    indirect=True,
+)
+def test_green_contention_and_cancellation(sync_runtime: RunSync) -> None:
+    sync_runtime(_check_green_contention)
+
+
+def test_async_calls(async_runtime: AsyncRuntime) -> None:
+    lock = Lock()
+
+    @routine
+    async def inner() -> None:
+        async with lock as entered:
+            assert assert_type(entered, Lock) is lock
+            await async_runtime.checkpoint()
+            with pytest.raises(RuntimeError, match="Use await function.a"), lock:
+                pass
+            with pytest.raises(RuntimeError, match="Use await function.a"):
+                lock.__exit__(None, None, None)
+            with pytest.raises(RuntimeError):
+                async with lock:
+                    pass
+
+    @routine
+    async def outer() -> None:
+        await inner.a()
+
+    async def main() -> None:
+        # Creating the acquisition coroutine must not acquire the lock.
+        call = lock.__aenter__()
+        async with lock:
+            pass
+        assert assert_type(await call, Lock) is lock
+        await lock.__aexit__(None, None, None)
+        with pytest.raises(RuntimeError):
+            await lock.__aexit__(None, None, None)
+        await outer.a()
+        with pytest.raises(ValueError, match="body failed"):
+            async with lock:
+                raise ValueError("body failed")
+        async with lock:
+            pass
+        # Ordinary ownership is also valid inside an async function.
+        with lock:
+            pass
+
+        # A failed ordinary routine must not leak ordinary dispatch into async work.
+        @routine
+        async def fails() -> None:
+            raise ValueError("routine failed")
+
+        with pytest.raises(ValueError):
+            fails()
+        await outer.a()
+
+    async_runtime.run(main)
+
+
+def test_async_contention_and_ownership(async_runtime: AsyncRuntime) -> None:
+    lock = Lock()
+
+    async def main() -> None:
+        held = async_runtime.event()
+        attempted = async_runtime.event()
+        order = []
+
+        async def owner() -> None:
+            async with lock:
+                held.set()
+                await attempted.wait()
+                await async_runtime.checkpoint()
+                assert order == []
+                order.append("owner")
+
+        @routine
+        async def nested() -> None:
+            async with lock:
+                order.append("waiter")
+
+        async def waiter() -> None:
+            await held.wait()
+            with pytest.raises(RuntimeError):
+                await lock.__aexit__(None, None, None)
+            attempted.set()
+            await nested.a()
+
+        await async_runtime.concurrently(owner, waiter)
+        assert order == ["owner", "waiter"]
+
+    async_runtime.run(main)
+
+
+def test_cancelled_acquisition_does_not_take_lock(async_runtime: AsyncRuntime) -> None:
+    lock = Lock()
+
+    async def waiter() -> None:
+        async with lock:
+            pytest.fail("cancelled waiter acquired the lock")
+
+    async def main() -> None:
+        held = async_runtime.event()
+        cancelled = async_runtime.event()
+
+        async def owner() -> None:
+            async with lock:
+                held.set()
+                await cancelled.wait()
+
+        async def cancel_waiter() -> None:
+            await held.wait()
+            try:
+                await async_runtime.cancel(waiter)
+            finally:
+                cancelled.set()
+
+        await async_runtime.concurrently(owner, cancel_waiter)
+        async with lock:
+            pass
+
+    async_runtime.run(main)
+
+
+def test_thread_and_async_handoff(async_runtime: AsyncRuntime) -> None:
+    lock = Lock()
+    held = Event()
+    release = Event()
+    attempted = Event()
+    acquired = Event()
+
+    def worker() -> None:
+        with lock:
+            held.set()
+            assert release.wait(2)
+        assert attempted.wait(2)
+        with lock:
+            acquired.set()
+
+    async def main() -> None:
+        while not held.is_set():
+            await async_runtime.checkpoint()
+
+        async def signal() -> None:
+            await async_runtime.checkpoint()
+            release.set()
+
+        async def waiter() -> None:
+            async with lock:
+                attempted.set()
+                await async_runtime.checkpoint()
+                assert not acquired.is_set()
+
+        await async_runtime.concurrently(waiter, signal)
+        while not acquired.is_set():
+            await async_runtime.checkpoint()
+
+    with ThreadPoolExecutor(max_workers=1) as pool:
+        future = pool.submit(worker)
+        try:
+            async_runtime.run(main)
+        finally:
+            release.set()
+            attempted.set()
+        future.result(timeout=2)
+
+
+def test_asyncio_and_trio_share_lock() -> None:
+    import asyncio
+
+    import trio
+    from trio.testing import wait_all_tasks_blocked
+
+    lock = Lock()
+    waiting = Event()
+    acquired = Event()
+
+    @routine
+    async def waiter() -> None:
+        async with lock:
+            acquired.set()
+
+    async def trio_main() -> None:
+        with trio.fail_after(5):
+            async with trio.open_nursery() as nursery:
+                nursery.start_soon(waiter.a)
+                # Confirm acquisition has suspended before asyncio releases the lock.
+                await wait_all_tasks_blocked()
+                assert not acquired.is_set()
+                waiting.set()
+
+    with ThreadPoolExecutor(max_workers=1) as pool:
+
+        @routine
+        async def owner() -> None:
+            async with lock:
+                future = pool.submit(trio.run, trio_main)
+                async with asyncio.timeout(5):
+                    while not waiting.is_set():
+                        await asyncio.sleep(0)
+                assert not acquired.is_set()
+            await asyncio.wrap_future(future)
+            assert acquired.is_set()
+            async with lock:
+                pass
+
+        asyncio.run(owner.a())
+
+
+@pytest.mark.parametrize("backend", ["asyncio", "trio"])
+def test_cancellation_while_waiting_and_holding(backend: str) -> None:
+    import anyio
+
+    lock = Lock()
+
+    async def main() -> None:
+        started = anyio.Event()
+        finished = anyio.Event()
+        scope = anyio.CancelScope()
+
+        async def waiter() -> None:
+            with scope:
+                started.set()
+                async with lock:
+                    pytest.fail("cancelled waiter acquired the lock")
+            finished.set()
+
+        async with anyio.create_task_group() as group:
+            async with lock:
+                group.start_soon(waiter)
+                await started.wait()
+                scope.cancel()
+                await finished.wait()
+            async with lock:
+                pass
+
+        with anyio.CancelScope() as owner_scope:
+            async with lock:
+                owner_scope.cancel()
+                await anyio.lowlevel.checkpoint()
+        assert owner_scope.cancelled_caught
+        async with lock:
+            pass
+
+    anyio.run(main, backend=backend)

noio/conftest.py

@@ -0,0 +1,160 @@
+import subprocess
+import sys
+import sysconfig
+from collections.abc import Awaitable
+from collections.abc import Callable
+from collections.abc import Coroutine
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass
+from functools import partial
+from time import sleep
+from typing import Any
+from typing import Protocol
+
+import pytest
+
+
+class RunAsync(Protocol):
+    def __call__[R](self, fn: Callable[[], Coroutine[Any, Any, R]]) -> R: ...
+
+
+type AsyncCall = Callable[[], Coroutine[Any, Any, None]]
+
+
+class RunConcurrently(Protocol):
+    async def __call__(self, *functions: AsyncCall) -> None: ...
+
+
+class AsyncEvent(Protocol):
+    def set(self) -> None: ...
+
+    async def wait(self) -> object: ...
+
+
+@dataclass(frozen=True)
+class AsyncRuntime:
+    run: RunAsync
+    checkpoint: Callable[[], Awaitable[None]]
+    event: Callable[[], AsyncEvent]
+    concurrently: RunConcurrently
+    cancel: Callable[[AsyncCall], Awaitable[None]]
+
+
+@pytest.fixture(params=["asyncio", "trio", "anyio-asyncio", "anyio-trio"])
+def async_runtime(request: pytest.FixtureRequest) -> AsyncRuntime:
+    import asyncio
+
+    import anyio
+    import trio
+
+    backend: str = request.param
+
+    def run[R](fn: Callable[[], Coroutine[Any, Any, R]]) -> R:
+        if backend == "asyncio":
+            return asyncio.run(fn())
+        if backend == "trio":
+            return trio.run(fn)
+        return anyio.run(fn, backend=backend.removeprefix("anyio-"))
+
+    async def checkpoint() -> None:
+        if backend == "asyncio":
+            await asyncio.sleep(0)
+        elif backend == "trio":
+            await trio.lowlevel.checkpoint()
+        else:
+            await anyio.lowlevel.checkpoint()
+
+    def event() -> AsyncEvent:
+        if backend == "asyncio":
+            return asyncio.Event()
+        if backend == "trio":
+            return trio.Event()
+        return anyio.Event()
+
+    async def concurrently(*functions: AsyncCall) -> None:
+        if backend == "asyncio":
+            async with asyncio.TaskGroup() as tasks:
+                for fn in functions:
+                    tasks.create_task(fn())
+        elif backend == "trio":
+            async with trio.open_nursery() as nursery:
+                for fn in functions:
+                    nursery.start_soon(fn)
+        else:
+            async with anyio.create_task_group() as group:
+                for fn in functions:
+                    group.start_soon(fn)
+
+    async def cancel(fn: AsyncCall) -> None:
+        if backend == "asyncio":
+
+            async def cancelled() -> None:
+                task = asyncio.current_task()
+                assert task is not None
+                task.cancel()
+                await fn()
+
+            with pytest.raises(asyncio.CancelledError):
+                await asyncio.create_task(cancelled())
+        elif backend == "trio":
+            with trio.CancelScope() as scope:
+                scope.cancel()
+                await fn()
+            assert scope.cancelled_caught
+        else:
+            with anyio.CancelScope() as anyio_scope:
+                anyio_scope.cancel()
+                await fn()
+            assert anyio_scope.cancelled_caught
+
+    return AsyncRuntime(run, checkpoint, event, concurrently, cancel)
+
+
+type SyncCheck = Callable[[Callable[[], None]], None]
+type RunSync = Callable[[SyncCheck], None]
+
+
+@pytest.fixture(
+    params=[
+        "main-thread",
+        "worker-thread",
+        "gevent",
+        "gevent-patched-before-import",
+        "gevent-patched-after-import",
+    ]
+)
+def sync_runtime(request: pytest.FixtureRequest) -> RunSync:
+    """Run a module-level check, passing the runtime's scheduling checkpoint.
+
+    Gevent subprocesses import checks by name, so they must be module-level functions.
+    """
+    mode: str = request.param
+    if mode.startswith("gevent") and sysconfig.get_config_var("Py_GIL_DISABLED"):
+        pytest.skip("gevent does not support free-threaded CPython")
+
+    def run(check: SyncCheck) -> None:
+        if mode == "main-thread":
+            check(partial(sleep, 0))
+        elif mode == "worker-thread":
+            with ThreadPoolExecutor(max_workers=1) as executor:
+                executor.submit(check, partial(sleep, 0)).result(timeout=2)
+        else:
+            bootstrap = ""
+            if mode == "gevent-patched-after-import":
+                bootstrap += "import noio\n"
+            if mode != "gevent":
+                bootstrap += "from gevent import monkey\nmonkey.patch_all()\n"
+            bootstrap += (
+                "import gevent, importlib, sys\n"
+                "check = getattr(importlib.import_module(sys.argv[1]), sys.argv[2])\n"
+                "gevent.spawn(check, lambda: gevent.sleep(0)).get(timeout=2)\n"
+            )
+            result = subprocess.run(
+                [sys.executable, "-c", bootstrap, check.__module__, check.__name__],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            assert result.returncode == 0, result.stdout + result.stderr
+
+    return run

noio/gevent_test.py

@@ -0,0 +1,35 @@
+import subprocess
+import sys
+import sysconfig
+
+import pytest
+
+
+@pytest.mark.skipif(
+    not sysconfig.get_config_var("Py_GIL_DISABLED"),
+    reason="requires a free-threaded CPython build",
+)
+@pytest.mark.xfail(
+    strict=True,
+    raises=AssertionError,
+    reason="gevent requires the GIL; revisit sync_runtime skips when this passes",
+)
+def test_gevent_preserves_disabled_gil() -> None:
+    # Ignore PYTHON_GIL overrides so this probes gevent's default behavior.
+    # Keep imports isolated from the rest of the test suite.
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-E",
+            "-c",
+            "import sys\n"
+            "assert not sys._is_gil_enabled()\n"
+            "import gevent\n"
+            "print(sys._is_gil_enabled())\n",
+        ],
+        capture_output=True,
+        text=True,
+        timeout=10,
+        check=True,
+    )
+    assert result.stdout.strip() == "False", result.stderr

noio/routine.md

@@ -0,0 +1,35 @@
+Routine
+========
+
+Start with regular functions, which need no decorator.
+When a function also needs to support coroutine libraries,
+write its implementation as an async function decorated with `@noio.routine`.
+Existing callers can continue calling it normally.
+
+Inside a routine, use `await function.a(...)` to call other routines.
+
+Methods
+-------
+
+The `@routine` decorator works on methods.
+If you're using it on a classmethod or staticmethod,
+be sure to put classmethod or staticmethod directly above the function,
+and this decorator above that.
+
+```python
+import asyncio
+from typing import Self
+import noio
+
+class Greeter:
+    def __init__(self, name: str):
+        self.name = name
+
+    @noio.routine
+    @classmethod
+    async def create(cls, name: str) -> Self:
+        return cls(name)
+
+assert Greeter.create("world").name == "world"
+assert asyncio.run(Greeter.create.a("world")).name == "world"
+```