#+TITLE: Some AsyncIO terms

I often find myself confused by a few common terms used throughout
asyncio, accidentally interchanging them with each other and then
wondering why things are failing, or why they don't run.

The best way to deeply understand generators, coroutines, async
generators and the rest in Python would be to understand them with
context as they were introduced; the behavior makes sense when
considered incrementally but not necessarily while looking backwards
from where we are today.

*  Coroutine
- async def, but no yield.
- "Asynchronous data consumers"

* Async Generator 
- async def and yield.
- "Asynchronous data producers"
  
* Generator
- yield
- "Data producers"

* Function
- The standard.
  
* Generator based coroutines
- Generators explicitly tagged as a coroutine
- Deprecated and slated for removal in Python 3.10
  
* An example
#+begin_src python :results output
import asyncio

def function():
    print("this is a function")


async def coroutine():
    print("this is a coroutine")


def generator():
    print("generator step 1")
    yield 1

    print("generator step 2")
    yield 2


async def async_generator():
    print("async generator step 1")
    yield 1

    print("async generator step 2")
    yield 2


async def main():
    print(f"Call {function}")
    function()

    print(f"\nCall {coroutine}")
    await coroutine()

    print(f"\nCall {generator}")
    for x in generator():
        print(x)

    print(f"\nCall {async_generator}")
    async for x in async_generator():
        print(x)

asyncio.run(main())
#+end_src

#+RESULTS:
#+begin_example
Call <function function at 0x7ff8cf6c51f0>
this is a function

Call <function coroutine at 0x7ff8cf564c10>
this is a coroutine

Call <function generator at 0x7ff8ceec28b0>
generator step 1
1
generator step 2
2

Call <function async_generator at 0x7ff8ceec25e0>
async generator step 1
1
async generator step 2
2
#+end_example

* Future
- Represents the result of a computation
- Can be awaited

* Task
- asyncio.task.Task: "A coroutine wrapped in a future"
- A Task is a Future
- Strictly tied to a given event loop.
- Responsible for "kicking" a generator along [fn:aosa]  with steps
  
#+begin_src python3


#+end_src
  

* References:
** Peps
- Pep 255: Generators
- Pep 342: Coroutines with enhanced generators
- Pep 380: Delegating to a subgenerator
- Pep 492: Coroutines with async and await
- Pep 525: Async generators

** https://snarky.ca/how-the-heck-does-async-await-work-in-python-3-5/

[fn:so] Generators vs Async Generators
[fn:aosa] I learned this from the AoSA book.

** Types
*** https://docs.python.org/3/library/collections.abc.html#collections.abc.AsyncGenerator