Update the section about coroutines.

python · ericsnowcurrently · Aug 19, 2024 · Aug 20, 2024 · Aug 19, 2024 · Aug 20, 2024
commit f7f176994a351922aee6b3b718f34b9f341b5795
diff --git a/Doc/howto/concurrency.rst b/Doc/howto/concurrency.rst
@@ -575,69 +575,32 @@ As the work on isolation wraps up, improvements will shift to focus
 on performance and memory usage.  Thus the overhead associated with
 using multiple interpreters will drastically decrease over time.
 
+Coroutines are contagious
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
+Coroutines can be an effective mechanism for letting a program's
+non-blocking code run while simultaneously waiting for blocking code
+to finish.  The tricky part is that the underlying machinery (the
+:ref:`event loop <asyncio-event-loop>`) relies on each coroutine
+explicitly yielding control at the appropriate moments.
 
+Normal functions do not follow this pattern, so they cannot take
+advantage of that cooperative scheduling to avoid blocking
+the program.  Thus coroutines and non-coroutines don't mix well.
+While there are tools for wrapping normal functions to act like
+coroutines, they are often converted into coroutines instead.
+At that point, if any non-async code relies on the function then
+either you'll need to convert the other code a coroutine or you'll
+need to keep the original non-async implementation around along
+with the new, almost identical async one.
 
+You can see how that can proliferate, leading to possible extra
+maintenance/development costs.
 
-Coroutines (Async/Await)
-^^^^^^^^^^^^^^^^^^^^^^^^
 
-The use of :term:`coroutines <coroutine>` for concurrency has been
-around a long time and has grown in popularity in the software world,
-particularly with the addition of ``async/await`` syntax in
-various languages.
 
-Python has supported coroutines to some degree since the beginning.
-The best example is :pypi:`twisted`, which has provided this concurrency
-model for decades.  For most of that time :pypi:`!twisted` did it
-primarily through callbacks and a form of "promises"/"futures".
 
-Explicit support for coroutines in Python really started with the
-introduction of :term:`generators <generator>` in Python 2.2
-(:pep:`255`).  In Python 2.5 (:pep:`342`), :term:`!generators` were
-tweaked to explicitly support use as coroutines.  That went a step
-further in Python 3.3 with the addition of ``yield from`` (:pep:`380`)
-and the :mod:`asyncio` module (:pep:`3156`).  Finally, in Python 3.5
-(:pep:`492`), we got dedicated ``async/await`` syntax
-and :ref:`a dedicated protocol <coroutine-protocol>`
-for :term:`!coroutine` objects.
 
-There are three main pieces to using coroutines:
-
-* coroutines (non-blocking, yield control instead)
-* an event loop (schedules coroutines)
-* coroutine wrappers around blocking operations
-
-A :term:`coroutine function` looks *almost* the same as a regular
-function.  It is a non-blocking function that *cooperatively* yields
-control of the program to other coroutines, which in turn yield control
-back (eventually).  At those points of synchronization,
-coroutines often provide data to one another.
-
-The event loop is what keeps track of which coroutines have yielded
-control and which should get control next.
-
-Generally a coroutine needs to avoid doing anything that takes very long
-before yielding control back to the event loop.  Any blocking operation
-in a coroutine, like waiting on a socket, has to be implemented in a way
-that only waits a little while, yields, and then waits again, etc. until
-ready.  The alternative is to wrap the blocking operation/function
-in some sort of "future" coroutine that yields until the blocking
-operation completes.  The event loop can also fill that role
-to an extent.
-
-In addition to support for coroutines in the language, Python's stdlib
-provides the :mod:`asyncio` module, which includes:
-
-* an event loop
-* a number of useful coroutines
-* a variety of helpful APIs that build on coroutines and the event loop
-
-One of the main challenges with using coroutines is that they do not
-normally mix well with non-coroutines.  As a result, ``async/await``
-can be contagious, requiring surrounding code to be async.  This can
-lead to having the same thing implemented twice, once normal and once
-async, with significant code duplication.
 
 Multi-processing
 ^^^^^^^^^^^^^^^^