bpo-32309: Implement asyncio.to_thread() (GH-20143)
Implements `asyncio.to_thread`, a coroutine for asynchronously running IO-bound functions in a separate thread without blocking the event loop. See the discussion starting from [here](https://github.com/python/cpython/pull/18410#issuecomment-628930973) in GH-18410 for context.
Automerge-Triggered-By: @aeros
diff --git a/Doc/library/asyncio-api-index.rst b/Doc/library/asyncio-api-index.rst
index d5b5659..047e5bb 100644
--- a/Doc/library/asyncio-api-index.rst
+++ b/Doc/library/asyncio-api-index.rst
@@ -48,6 +48,9 @@
* - :class:`Task`
- Task object.
+ * - :func:`to_thread`
+ - Asychronously run a function in a separate OS thread.
+
* - :func:`run_coroutine_threadsafe`
- Schedule a coroutine from another OS thread.
diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
index 2e96339..7c27040 100644
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -602,6 +602,62 @@
# ...
+Running in Threads
+==================
+
+.. coroutinefunction:: to_thread(func, /, \*args, \*\*kwargs)
+
+ Asynchronously run function *func* in a separate thread.
+
+ Any \*args and \*\*kwargs supplied for this function are directly passed
+ to *func*.
+
+ Return an :class:`asyncio.Future` which represents the eventual result of
+ *func*.
+
+ This coroutine function is primarily intended to be used for executing
+ IO-bound functions/methods that would otherwise block the event loop if
+ they were ran in the main thread. For example::
+
+ def blocking_io():
+ print(f"start blocking_io at {time.strftime('%X')}")
+ # Note that time.sleep() can be replaced with any blocking
+ # IO-bound operation, such as file operations.
+ time.sleep(1)
+ print(f"blocking_io complete at {time.strftime('%X')}")
+
+ async def main():
+ print(f"started main at {time.strftime('%X')}")
+
+ await asyncio.gather(
+ asyncio.to_thread(blocking_io),
+ asyncio.sleep(1))
+
+ print(f"finished main at {time.strftime('%X')}")
+
+
+ asyncio.run(main())
+
+ # Expected output:
+ #
+ # started main at 19:50:53
+ # start blocking_io at 19:50:53
+ # blocking_io complete at 19:50:54
+ # finished main at 19:50:54
+
+ Directly calling `blocking_io()` in any coroutine would block the event loop
+ for its duration, resulting in an additional 1 second of run time. Instead,
+ by using `asyncio.to_thread()`, we can run it in a separate thread without
+ blocking the event loop.
+
+ .. note::
+
+ Due to the :term:`GIL`, `asyncio.to_thread()` can typically only be used
+ to make IO-bound functions non-blocking. However, for extension modules
+ that release the GIL or alternative Python implementations that don't
+ have one, `asyncio.to_thread()` can also be used for CPU-bound functions.
+
+
Scheduling From Other Threads
=============================
diff --git a/Doc/whatsnew/3.9.rst b/Doc/whatsnew/3.9.rst
index 593f523..037e105 100644
--- a/Doc/whatsnew/3.9.rst
+++ b/Doc/whatsnew/3.9.rst
@@ -282,6 +282,12 @@
Added :class:`asyncio.PidfdChildWatcher`, a Linux-specific child watcher
implementation that polls process file descriptors. (:issue:`38692`)
+Added a new :term:`coroutine` :func:`asyncio.to_thread`. It is mainly used for
+running IO-bound functions in a separate thread to avoid blocking the event
+loop, and essentially works as a high-level version of
+:meth:`~asyncio.loop.run_in_executor` that can directly take keyword arguments.
+(Contributed by Kyle Stanley and Yury Selivanov in :issue:`32309`.)
+
compileall
----------