elaborate explanation in docs and add a whatsnew entry

python · carljm · May 1, 2023 · Mar 20, 2023 · Mar 20, 2023 · Mar 20, 2023
commit 402c3172dc2942642f2929943bd3982388b25e64
@@ -535,10 +535,20 @@ Eager Task Factory
     A task factory for eager task execution.
 
     When using this factory (via ``loop.set_task_factory(asyncio.eager_task_factory)``),
-    coroutines that are able to complete synchronously (without suspending)
+    coroutines that are able to complete synchronously (without blocking)
     are returned immediately as a completed :class:`Future`.
 
-    A regular :class:`Task` is returned otherwise, at the first suspension of *coro*.
+    This task factory tries to execute the coroutine `coro` immediately
+    (before creating and scheduling a task to the event loop), until it either
+    blocks, returns, or raises.
+    If the coroutine returns or raises, a :class:`Future` is returned, and no
+    task is created or scheduled to the event loop. If the coroutine blocks,
+    a :class:`Task` is constructed and returned at that point.
+
+    .. note::
+
+        The fact that the coroutine starts execution immediately is a semantic change,
+        and might lead to application behavior changes, depending on the application.
 
     .. versionadded:: 3.12
 

diff --git a/Doc/whatsnew/3.12.rst b/Doc/whatsnew/3.12.rst
@@ -532,6 +532,11 @@ Optimizations
   replacement strings containing group references by 2--3 times.
   (Contributed by Serhiy Storchaka in :gh:`91524`.)
 
+* Added :func:`asyncio.eager_task_factory` and :func:`asyncio.create_eager_task_factory`
+  functions to allow opting an event loop in to eager task execution,
+  speeding up some use-cases by up to 50%.
+  (Contributed by Itamar O in :gh:`102853`)
+
 
 CPython bytecode changes
 ========================