Added opt-in locking of first detected async backend

docs/basics.rst

@@ -54,10 +54,21 @@ native ``run()`` function of the backend library::
 
  trio.run(main)
 
+Unless you're using trio-asyncio_, you will probably want to reduce the overhead caused
+by dynamic backend detection by setting the ``ANYIO_BACKEND`` environment variable to
+either ``asyncio`` or ``trio``, depending on your backend of choice. This will enable
+AnyIO to avoid checking which flavor of async event loop you're running when you call
+one of AnyIO's functions – a check that typically involves at least one system call.
+
 .. versionchanged:: 4.0.0
  On the ``asyncio`` backend, ``anyio.run()`` now uses a back-ported version of
  :class:`asyncio.Runner` on Pythons older than 3.11.
 
+.. versionchanged:: 4.4.0
+ Added support for forcing a specific backend via ``ANYIO_BACKEND``
+
+.. _trio-asyncio: https://github.com/python-trio/trio-asyncio
+
 .. _backend options:
 
 Backend specific options

docs/versionhistory.rst

@@ -5,6 +5,9 @@ This library adheres to `Semantic Versioning 2.0 <https://semver.org/>`_.
 
 **UNRELEASED**
 
+- Added an opt-in performance optimization that decreases AnyIO's overhead (compared to
+ native calls on the selected async backend), used by setting the ``ANYIO_BACKEND``
+ environment variable to ``auto``, ``asyncio`` or ``trio``
 - Added support for the ``from_uri()``, ``full_match()``, ``parser`` methods/properties
  in ``anyio.Path``, newly added in Python 3.13
  (`#737 <https://github.com/agronholm/anyio/issues/737>`_)

src/anyio/_core/_eventloop.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import math
+import os
 import sys
 import threading
 from collections.abc import Awaitable, Callable, Generator
@@ -26,19 +27,26 @@
 
 threadlocals = threading.local()
 loaded_backends: dict[str, type[AsyncBackend]] = {}
+forced_backend_name = os.getenv("ANYIO_BACKEND")
+forced_backend: type[AsyncBackend] | None = None
 
 
 def run(
  func: Callable[[Unpack[PosArgsT]], Awaitable[T_Retval]],
  *args: Unpack[PosArgsT],
- backend: str = "asyncio",
+ backend: str | None = None,
  backend_options: dict[str, Any] | None = None,
 ) -> T_Retval:
  """
  Run the given coroutine function in an asynchronous event loop.
 
  The current thread must not be already running an event loop.
 
+ The backend will be chosen using the following priority list:
+ * the ``backend`` argument, if not ``None``
+ * the ``ANYIO_BACKEND`` environment variable
+ * ``asyncio``
+
  :param func: a coroutine function
  :param args: positional arguments to ``func``
  :param backend: name of the asynchronous event loop implementation – currently
@@ -58,6 +66,7 @@ def run(
  else:
  raise RuntimeError(f"Already running {asynclib_name} in this thread")
 
+ backend = backend or os.getenv("ANYIO_BACKEND") or "asyncio"
  try:
  async_backend = get_async_backend(backend)
  except ImportError as exc:
@@ -124,7 +133,16 @@ def current_time() -> float:
 
 
 def get_all_backends() -> tuple[str, ...]:
- """Return a tuple of the names of all built-in backends."""
+ """
+ Return a tuple of the names of all built-in backends.
+
+ If the ``ANYIO_BACKEND`` environment variable was set, then the returned tuple will
+ only contain that backend.
+
+ """
+ if forced_backend_name:
+ return (forced_backend_name,)
+
  return BACKENDS
 
 
@@ -152,15 +170,23 @@ def claim_worker_thread(
 
 
 def get_async_backend(asynclib_name: str | None = None) -> type[AsyncBackend]:
- if asynclib_name is None:
- asynclib_name = sniffio.current_async_library()
+ global forced_backend
+
+ if forced_backend is not None:
+ return forced_backend
 
  # We use our own dict instead of sys.modules to get the already imported back-end
  # class because the appropriate modules in sys.modules could potentially be only
  # partially initialized
+ asynclib_name = (
+ asynclib_name or forced_backend_name or sniffio.current_async_library()
+ )
  try:
  return loaded_backends[asynclib_name]
  except KeyError:
  module = import_module(f"anyio._backends._{asynclib_name}")
  loaded_backends[asynclib_name] = module.backend_class
+ if asynclib_name == forced_backend_name:
+ forced_backend = module.backend_class
+
  return module.backend_class

tests/test_pytest_plugin.py

@@ -2,6 +2,7 @@
 
 import pytest
 from _pytest.logging import LogCaptureFixture
+from _pytest.monkeypatch import MonkeyPatch
 from _pytest.pytester import Pytester
 
 from anyio import get_all_backends
@@ -418,3 +419,29 @@ async def test_anyio_mark_last_fail(x):
  result.assert_outcomes(
  passed=2 * len(get_all_backends()), xfailed=2 * len(get_all_backends())
  )
+
+
+@pytest.mark.parametrize("backend_name", get_all_backends())
+def test_lock_backend(
+ backend_name: str, testdir: Pytester, monkeypatch: MonkeyPatch
+) -> None:
+ testdir.makepyfile(
+ f"""
+ import os
+ import sys
+
+ import pytest
+ import anyio
+
+ pytestmark = pytest.mark.anyio
+
+ async def test_sleep(anyio_backend_name):
+ assert anyio.get_all_backends() == (anyio_backend_name,)
+ assert anyio_backend_name == {backend_name!r}
+ await anyio.sleep(0)
+ """
+ )
+
+ monkeypatch.setenv("ANYIO_BACKEND", backend_name)
+ result = testdir.runpytest_subprocess(*pytest_args)
+ result.assert_outcomes(passed=1)