Python 协程 - Coroutines

 协程 - Coroutines

 Awaitable Objects,
     Awaitable Objects 通常由 __await__() 生成, 而
     Coroutine objects 是由 async def 关键字定义的函数 return 的 Awaitable Objects.
     Note,
         被 types.coroutine() or asyncio.coroutine() 装饰的生成器迭代器对象(generator iterator objects)
         是没有通过 __await__() 生成的 Awaitable Objects.

     object.__await__(self) 必须 return 一个 iterator, 用来生成 Awaitable Objects.
     如, asyncio.Future 执行这个方法一兼容 await 表达式.
     See also PEP 492 for additional information about awaitable objects.

 Coroutine Objects,
     Coroutine objects 是 awaitable objects, 是一个 __await__() return 的 iterator,
     Coroutine 的执行就是对 __await__() return 的 iterator 的迭代. 跟 iterator 一样,
     当 coroutine 执行完毕后 raises StopIteration, 这个异常的 value 属性是执行返回的结果.
     如果 coroutine raises an exception, 这个异常会被'冒泡式' 返回. Coroutines 不可以直接
     raise 一个未加工过的 StopIteration exceptions.

     Coroutines 有如下方法(与 generator 相似), 但是与 generators 不同的是 coroutines 不对
     迭代提供直接的支持. Python version 3.5.2, 之后 在一个 coroutine 上多次 await 返回
     RuntimeError exception.

         coroutine.send(value)
             开始或者恢复 coroutine 的执行. 如果参数 value = None, 为对 coroutine 的预激活.
             若 value 不是 None, 这个方法相当于 iterator 的 send() 方法, 将使 coroutine 暂停.
             方法的返回 (return value, StopIteration, or other exception) 上面已经描述过.

         coroutine.throw(type[, value[, traceback]])
             在 coroutine raise specified exception.
             这个方法对应 iterator 中的 throw() 方法, 会使 coroutine 暂停

         coroutine.close()
             使 coroutine 去初始化并退出. 对应 iterator 的 close() 方法.

 Asynchronous Iterators
     一个 asynchronous iterable 通过调用 __aiter__() 得到一个 asynchronous iterator.
     Asynchronous iterators 可以被用在一个 async 声明中.

     object.__aiter__(self)
         返回一个 asynchronous iterator 对象.

     object.__anext__(self)
         从 iterator 中返回一个 awaitable 对象. 当 iterator 结束的时候
         raise  StopAsyncIteration error exception

     asynchronous iterable object 的例子,

         class Reader:
             async def readline(self):
                 ...

             def __aiter__(self):
             return self

             async def __anext__(self):
                 val = await self.readline()
                 if val == b'':
                     raise StopAsyncIteration
                 return val

 Asynchronous Context Managers,
     asynchronous context manager 是一个能够暂停执行的 context manager .
     Asynchronous context managers 可以通过 async with 关键字声明.
     object.__aenter__(self)
         与 __enter__() 类似, 不同之处在于 方法必须返回一个 awaitable 对象.

     object.__aexit__(self, exc_type, exc_value, traceback),
         与 __exit__() 类似, 不同之处在于 方法必须返回一个 awaitable 对象.

     asynchronous context manager 的例子,
         class AsyncContextManager:
             async def __aenter__(self):
                 await log('entering context')

             async def __aexit__(self, exc_type, exc, tb):
                 await log('exiting context')

 Reference,
     Python doc. https://docs.python.org/3/reference/datamodel.html#coroutines