- Significantly reduce article size. Remove both example sections & "Which concurrency do I want" section.

Author: anordin95

Doc/howto/a-conceptual-overview-of-asyncio.rst

@@ -10,9 +10,6 @@ This article seeks to help you build a sturdy mental model of how asyncio
 fundamentally works.
 Something that will help you understand the how and why behind the recommended
 patterns.
-The final section, :ref:`which_concurrency_do_I_want`, zooms out a bit and
-compares the common approaches to concurrency -- multiprocessing,
-multithreading & asyncio -- and describes where each is most useful.
 
 During my own asyncio learning process, a few aspects particually drove my
 curiosity (read: drove me nuts).
@@ -27,15 +24,6 @@ of this article.
 - How would I go about writing my own asynchronous variant of some operation?
   Something like an async sleep, database request, etc.
 
-The first two sections feature some examples but are generally focused on theory
-and explaining concepts.
-The next two sections are centered around examples, focused on further
-illustrating and reinforcing ideas practically.
-
-.. contents:: Sections
-    :depth: 1
-    :local:
-
 ---------------------------------------------
 A conceptual overview part 1: the high-level
 ---------------------------------------------
@@ -489,368 +477,3 @@ For reference, you could implement it without futures, like so::
             else:
                 await YieldToEventLoop()
 
-
-.. _anaylzing-control-flow-example:
-
-----------------------------------------------
-Analyzing an example programs control flow
-----------------------------------------------
-
-We'll walkthrough, step by step, a simple asynchronous program following along
-in the key methods of Task & Future that are leveraged when asyncio is
-orchestrating the show.
-
-
-===============
-Task.step
-===============
-
-The actual method that invokes a Tasks coroutine:
-``asyncio.tasks.Task.__step_run_and_handle_result`` is about 80 lines long.
-For the sake of clarity, I've removed all of the edge-case error handling,
-simplified some aspects and renamed it, but the core logic remains unchanged.
-
-::
-
-    1  class Task(Future):
-    2      ...
-    3      def step(self):
-    4          try:
-    5              awaited_task = self.coro.send(None)
-    6          except StopIteration as e:
-    7              super().set_result(e.value)
-    8          else:
-    9             awaited_task.add_done_callback(self.__step)
-    10         ...
-
-
-======================
-Example program
-======================
-
-::
-
-    # Filename: program.py
-    1  async def triple(val: int):
-    2      return val * 3
-    3
-    4  async def main():
-    5      triple_task = asyncio.Task(coro=triple(val=5))
-    6      tripled_val = await triple_task
-    7      return tripled_val + 2
-    8
-    9  loop = asyncio.new_event_loop()
-    10 main_task = asyncio.Task(main(), loop=loop)
-    11 loop.run_forever()
-
-=====================
-Control flow
-=====================
-
-At a high-level, this is how control flows:
-
-.. code-block:: none
-
-    1  program
-    2      event-loop
-    3          main_task.step
-    4              main()
-    5                  triple_task.__await__
-    6              main()
-    7          main_task.step
-    8      event-loop
-    9          triple_task.step
-    10             triple()
-    11         triple_task.step
-    12     event-loop
-    13         main_task.step
-    14             triple_task.__await__
-    15                 main()
-    16         main_task.step
-    17     event-loop
-
-And, in much more detail:
-
-1. Control begins in ``program.py``
-        Line 9 creates an event-loop, line 10 creates ``main_task`` and adds it to
-        the event-loop, line 11 indefinitely passes control to the event-loop.
-2. Control is now in the event-loop
-        The event-loop pops ``main_task`` off its queue, then invokes it by calling
-        ``main_task.step()``.
-3. Control is now in ``main_task.step``
-        We enter the try-block on line 4 then begin the coroutine ``main()`` on
-        line 5.
-4. Control is now in the coroutine: ``main()``
-        The Task ``triple_task`` is created on line 5 which adds it to the
-        event-loops queue. Line 6 ``await``\ s triple_task.
-        Remember, that calls ``Task.__await__`` then percolates any ``yield``\ s.
-5. Control is now in ``triple_task.__await__``
-        ``triple_task`` is not done given it was just created, so we enter
-        the first if-block on line 5 and ``yield`` the thing we'll be waiting
-        for -- ``triple_task``.
-6. Control is now in the coroutine: ``main()``
-        ``await`` percolates the ``yield`` and the yielded value -- ``triple_task``.
-7. Control is now in ``main_task.step``
-        The variable ``awaited_task`` is ``triple_task``.
-        No ``StopIteration`` was raised so the else in the try-block on line 8
-        executes.
-        A done-callback: ``main_task.step`` is added to the ``triple_task``.
-        The step method ends and returns to the event-loop.
-8. Control is now in the event-loop
-        The event-loop cycles to the next task in its queue.
-        The event-loop pops ``triple_task`` from its queue and invokes it by
-        calling ``triple_task.step()``.
-9. Control is now in ``triple_task.step``
-        We enter the try-block on line 4 then begin the coroutine ``triple()``
-        via line 5.
-10. Control is now in the coroutine: ``triple()``
-        It computes 3 times 5, then finishes and raises a ``StopIteration``
-        exception.
-11. Control is now in ``triple_task.step``
-        The ``StopIteration`` exception is caught so we go to line 7.
-        The return value of the coroutine ``triple()`` is embedded in the value
-        attribute of that exception.
-        ``Future.set_result()`` saves the result, marks the task as done and adds
-        the done-callbacks of ``triple_task`` to the event-loops queue.
-        The step method ends and returns control to the event-loop.
-12. Control is now in the event-loop
-        The event-loop cycles to the next task in its queue.
-        The event-loop pops ``main_task`` and resumes it by calling
-        ``main_task.step()``.
-13. Control is now in ``main_task.step``
-        We enter the try-block on line 4 then resume the coroutine ``main``
-        which will pick up again from where it ``yield``-ed.
-        Recall, it ``yield``-ed not in the coroutine, but in
-        ``triple_task.__await__`` on line 6.
-14. Control is now in ``triple_task.__await__``
-        We evaluate the if-statement on line 8 which ensures that ``triple_task``
-        was completed.
-        Then, it returns the result of ``triple_task`` which was saved earlier.
-        Finally that result is returned to the caller
-        (i.e. ``... = await triple_task``).
-15. Control is now in the coroutine: ``main()``
-        ``tripled_val`` is 15. The coroutine finishes and raises a
-        ``StopIteration`` exception with the return value of 17 attached.
-16. Control is now in ``main_task.step``
-        The ``StopIteration`` exception is caught and ``main_task`` is marked
-        as done and its result is saved.
-        The step method ends and returns control to the event-loop.
-17. Control is now in the event-loop
-        There's nothing in the queue.
-        The event-loop cycles aimlessly onwards.
-
-----------------------------------------------
-Barebones network I/O example
-----------------------------------------------
-
-Here we'll see a simple but thorough example showing how asyncio can offer an
-advantage over serial programs.
-The example doesn't rely on any asyncio operators (besides the event-loop).
-It's all non-blocking sockets & custom awaitables that help you see what's
-actually happening under the hood and how you could do something similar.
-
-Performing a database request across a network might take half a second or so,
-but that's ages in computer-time.
-Your processor could have done millions or even billions of things.
-The same is true for, say, requesting a website, downloading a car, loading a
-file from disk into memory, etc.
-The general theme is those are all input/output (I/O) actions.
-
-Consider performing two tasks: requesting some information from a server and
-doing some computation locally.
-A serial approach would look like: ping the server, idle while waiting for a
-response, receive the response, perform the local computation.
-An asynchronous approach would look like: ping the server, do some of the
-local computation while waiting for a response, check if the server is ready
-yet, do a bit more of the local computation, check again, etc.
-Basically we're freeing up the CPU to do other activities instead of scratching
-its belly button.
-
-This example has a server (a separate, local process) compute the sum of many
-samples from a Gaussian (i.e. normal) distribution.
-And the local computation finds the sum of many samples from a uniform
-distribution.
-As you'll see, the asynchronous approach runs notably faster, since progress
-can be made on computing the sum of many uniform samples, while waiting for
-the server to calculate and respond.
-
-=====================
-Serial output
-=====================
-
-.. code-block:: none
-
-    $ python serial_approach.py
-    Beginning server_request.
-    ====== Done server_request. total: -2869.04. Ran for: 2.77s. ======
-    Beginning uniform_sum.
-    ====== Done uniform_sum. total: 60001676.02. Ran for: 4.77s. ======
-    Total time elapsed: 7.54s.
-
-=====================
-Asynchronous output
-=====================
-
-.. code-block:: none
-
-    $ python async_approach.py
-    Beginning uniform_sum.
-    Pausing uniform_sum at sample_num: 26,999,999. time_elapsed: 1.01s.
-
-    Beginning server_request.
-    Pausing server_request. time_elapsed: 0.00s.
-
-    Resuming uniform_sum.
-    Pausing uniform_sum at sample_num: 53,999,999. time_elapsed: 1.05s.
-
-    Resuming server_request.
-    Pausing server_request. time_elapsed: 0.00s.
-
-    Resuming uniform_sum.
-    Pausing uniform_sum at sample_num: 80,999,999. time_elapsed: 1.05s.
-
-    Resuming server_request.
-    Pausing server_request. time_elapsed: 0.00s.
-
-    Resuming uniform_sum.
-    Pausing uniform_sum at sample_num: 107,999,999. time_elapsed: 1.04s.
-
-    Resuming server_request.
-    ====== Done server_request. total: -2722.46. ======
-
-    Resuming uniform_sum.
-    ====== Done uniform_sum. total: 59999087.62 ======
-
-    Total time elapsed: 4.60s.
-
-======================
-Code
-======================
-
-Now, we'll explore some of the most important snippets.
-
-Below is the portion of the asynchronous approach responsible for checking if
-the server's done yet.
-And, if not, yielding control back to the event-loop instead of idly waiting.
-I'd like to draw your attention to a specific part of this snippet.
-Setting a socket to non-blocking mode means the ``recv()`` call won't idle while
-waiting for a response.
-Instead, if there's no data to be read, it'll immediately raise a
-``BlockingIOError``.
-If there is data available, the ``recv()`` will proceed as normal.
-
-.. code-block:: python
-
-    class YieldToEventLoop:
-        def __await__(self):
-            yield
-    ...
-
-    async def get_server_data():
-        client = socket.socket()
-        client.connect(server.SERVER_ADDRESS)
-        client.setblocking(False)
-
-        while True:
-            try:
-                # For reference, the first argument to recv() is the maximum number
-                # of bytes to attempt to read. Setting it to 4096 means we could get 2
-                # bytes or 4 bytes, or even 4091 bytes, but not 4097 bytes back.
-                # However, if there are no bytes available to be read, this recv()
-                # will raise a BlockingIOError since the socket was set to
-                # non-blocking mode.
-                response = client.recv(4096)
-                break
-            except BlockingIOError:
-                await YieldToEventLoop()
-        return response
-
-
-And this is the portion of code responsible for asynchronously computing
-the uniform sums.
-It's designed to allow for working through the sum a portion at a time.
-The ``time_allotment`` argument to the coroutine function decides how long the sum
-function will iterate, in other words, synchronously hog control, before ceding
-back to the event-loop.
-
-.. code-block:: python
-
-    async def uniform_sum(n_samples: int, time_allotment: float) -> float:
-
-        start_time = time.time()
-
-        total = 0.0
-        for _ in range(n_samples):
-            total += random.random()
-
-            time_elapsed = time.time() - start_time
-            if time_elapsed > time_allotment:
-                await YieldToEventLoop()
-                start_time = time.time()
-
-        return total
-
-The above snippet was simplified a bit. Reading ``time.time()`` and evaluating
-an if-condition on every iteration for many, many iterations (in this case
-roughly a hundred million) more than eats up the runtime savings associated
-with the asynchronous approach.
-The actual implementation involves chunking the iteration, so you only perform
-the check every few million iterations.
-With that change, the asynchronous approach wins in a landslide.
-This is important to keep in mind.
-Too much checking or constantly jumping between tasks can ultimately cause more
-harm than good!
-
-The server, async & serial programs are available in full here:
-https://github.com/anordin95/a-conceptual-overview-of-asyncio/tree/main/barebones-network-io-example.
-
-.. _which_concurrency_do_I_want:
-
-------------------------------
-Which concurrency do I want
-------------------------------
-
-===========================
-multiprocessing
-===========================
-
-For any computationally bound work in Python, you likely want to use
-multiprocessing.
-Otherwise, the Global Interpreter Lock (GIL) will generally get in your way!
-For those who don't know, the GIL is a lock which ensures only one Python
-instruction is executed at a time.
-Of course, since processes are generally entirely independent from one another,
-the GIL in one process won't be impeded by the GIL in another process.
-Granted, I believe there are ways to also get around the GIL in a single process
-by leveraging C extensions or via subinterpreters.
-
-===========================
-multithreading & asyncio
-===========================
-
-Multithreading and asyncio are much more similar in where they're useful with
-Python: not at all for computationally-bound work, and crucially for I/O bound
-work.
-For applications that need to manage absolutely tons of distinct I/O connections
-or chunks-of-work, asyncio is a must.
-For example, a web server handling thousands of requests "simultaneously"
-(in quotes, because, as we saw, the frequent handoffs of control only create
-the illusion of simultaneous execution).
-Otherwise, I think the choice between which to use is somewhat down to taste.
-
-Multithreading maintains an OS managed thread for each chunk of work. Whereas
-asyncio uses Tasks for each work-chunk and manages them via the event-loop's
-queue.
-I believe the marginal overhead of one more chunk of work is a fair bit lower
-for asyncio than threads, which matters a lot for applications that need to
-manage many, many chunks of work.
-
-There are some other benefits associated with using asyncio.
-One is clearer visibility into when and where interleaving occurs.
-The code chunk between two awaits is certainly synchronous.
-Another is simpler debugging, since it's easier to attach and follow a trace and
-reason about code execution.
-With threading, the interleaving is more of a black-box.
-One benefit of multithreading is not really having to worry about greedy threads
-hogging execution, something that could happen with asyncio where a greedy
-coroutine never awaits and effectively stalls the event-loop.