协程与任务
**********

本节将简述用于协程与任务的高层级 API。

* 协程

* 可等待对象

* 运行 asyncio 程序

* 创建任务

* 休眠

* 并发运行任务

* 屏蔽取消操作

* 超时

* 简单等待

* 来自其他线程的日程安排

* 内省

* Task 对象

* 基于生成器的协程


协程
====

*协程* 通过 async/await 语法进行声明，是编写 asyncio 应用的推荐方式。
例如，以下代码段（需要 Python 3.7+）会打印 "hello"，等待 1 秒，再打印
"world":

   >>> import asyncio

   >>> async def main():
   ...     print('hello')
   ...     await asyncio.sleep(1)
   ...     print('world')

   >>> asyncio.run(main())
   hello
   world

注意：简单地调用一个协程并不会将其加入执行日程:

   >>> main()
   <coroutine object main at 0x1053bb7c8>

要真正运行一个协程，asyncio 提供了三种主要机制:

* "asyncio.run()" 函数用来运行最高层级的入口点 "main()" 函数 (参见上面
  的示例。)

* 等待一个协程。以下代码段会在等待 1 秒后打印 "hello"，然后 *再次* 等
  待 2 秒后打印 "world":

     import asyncio
     import time

     async def say_after(delay, what):
         await asyncio.sleep(delay)
         print(what)

     async def main():
         print(f"started at {time.strftime('%X')}")

         await say_after(1, 'hello')
         await say_after(2, 'world')

         print(f"finished at {time.strftime('%X')}")

     asyncio.run(main())

  预期的输出:

     started at 17:13:52
     hello
     world
     finished at 17:13:55

* "asyncio.create_task()" 函数用来并发运行作为 asyncio "任务" 的多个协
  程。

  让我们修改以上示例，*并发* 运行两个 "say_after" 协程:

     async def main():
         task1 = asyncio.create_task(
             say_after(1, 'hello'))

         task2 = asyncio.create_task(
             say_after(2, 'world'))

         print(f"started at {time.strftime('%X')}")

         # Wait until both tasks are completed (should take
         # around 2 seconds.)
         await task1
         await task2

         print(f"finished at {time.strftime('%X')}")

  注意，预期的输出显示代码段的运行时间比之前快了 1 秒:

     started at 17:14:32
     hello
     world
     finished at 17:14:34


可等待对象
==========

如果一个对象可以在 "await"  语句中使用，那么它就是 **可等待** 对象。许
多 asyncio API 都被设计为接受可等待对象。

*可等待* 对象有三种主要类型: **协程**, **任务** 和 **Future**.

-[ 协程 ]-

Python 协程属于 *可等待* 对象，因此可以在其他协程中被等待:

   import asyncio

   async def nested():
       return 42

   async def main():
       # Nothing happens if we just call "nested()".
       # A coroutine object is created but not awaited,
       # so it *won't run at all*.
       nested()

       # Let's do it differently now and await it:
       print(await nested())  # will print "42".

   asyncio.run(main())

重要:

  在本文档中 "协程" 可用来表示两个紧密关联的概念:

  * *协程函数*: 定义形式为 "async def" 的函数;

  * *协程对象*: 调用 *协程函数* 所返回的对象。

asyncio 也支持旧式的 基于生成器的 协程。

-[ 任务 ]-

*任务* 被用来设置日程以便 *并发* 执行协程。

当一个协程通过 "asyncio.create_task()" 等函数被打包为一个 *任务*，该协
程将自动排入日程准备立即运行:

   import asyncio

   async def nested():
       return 42

   async def main():
       # Schedule nested() to run soon concurrently
       # with "main()".
       task = asyncio.create_task(nested())

       # "task" can now be used to cancel "nested()", or
       # can simply be awaited to wait until it is complete:
       await task

   asyncio.run(main())

-[ Futures ]-

"Future" 是一种特殊的 **低层级** 可等待对象，表示一个异步操作的 **最终
结果**。

当一个 Future 对象 *被等待*，这意味着协程将保持等待直到该 Future 对象
在其他地方操作完毕。

在 asyncio 中需要 Future 对象以便允许通过 async/await 使用基于回调的代
码。

通常情况下 **没有必要** 在应用层级的代码中创建 Future 对象。

Future 对象有时会由库和某些 asyncio API 暴露给用户，用作可等待对象:

   async def main():
       await function_that_returns_a_future_object()

       # this is also valid:
       await asyncio.gather(
           function_that_returns_a_future_object(),
           some_python_coroutine()
       )

一个很好的返回对象的低层级函数的示例是 "loop.run_in_executor()"。


运行 asyncio 程序
=================

asyncio.run(coro, *, debug=False)

   执行 *coroutine* *coro* 并返回结果。

   此函数运行传入的协程，负责管理 asyncio 事件循环并 *完结异步生成器*
   。

   当有其他 asyncio 事件循环在同一线程中运行时，此函数不能被调用。

   如果 *debug* 为 "True"，事件循环将以调试模式运行。

   此函数总是会创建一个新的事件循环并在结束时关闭之。它应当被用作
   asyncio 程序的主入口点，理想情况下应当只被调用一次。

   示例:

      async def main():
          await asyncio.sleep(1)
          print('hello')

      asyncio.run(main())

   3.7 版新加入.

   備註:

     "asyncio.run()" 的源代码可以在 Lib/asyncio/runners.py 中找到。


创建任务
========

asyncio.create_task(coro, *, name=None)

   将 *coro* 协程 打包为一个 "Task" 排入日程准备执行。返回 Task 对象。

   *name* 不为 "None"，它将使用 "Task.set_name()" 来设为任务的名称。

   该任务会在 "get_running_loop()" 返回的循环中执行，如果当前线程没有
   在运行的循环则会引发 "RuntimeError"。

   此函数 **在 Python 3.7 中被加入**。在 Python 3.7 之前，可以改用低层
   级的 "asyncio.ensure_future()" 函数。

      async def coro():
          ...

      # In Python 3.7+
      task = asyncio.create_task(coro())
      ...

      # This works in all Python versions but is less readable
      task = asyncio.ensure_future(coro())
      ...

   3.7 版新加入.

   3.8 版更變: 添加了 "name" 形参。


休眠
====

coroutine asyncio.sleep(delay, result=None, *, loop=None)

   阻塞 *delay* 指定的秒数。

   如果指定了 *result*，则当协程完成时将其返回给调用者。

   "sleep()" 总是会挂起当前任务，以允许其他任务运行。

   Deprecated since version 3.8, will be removed in version 3.10:
   *loop* 形参。

   以下协程示例运行 5 秒，每秒显示一次当前日期:

      import asyncio
      import datetime

      async def display_date():
          loop = asyncio.get_running_loop()
          end_time = loop.time() + 5.0
          while True:
              print(datetime.datetime.now())
              if (loop.time() + 1.0) >= end_time:
                  break
              await asyncio.sleep(1)

      asyncio.run(display_date())


并发运行任务
============

awaitable asyncio.gather(*aws, loop=None, return_exceptions=False)

   *并发* 运行 *aws* 序列中的 可等待对象。

   如果 *aws* 中的某个可等待对象为协程，它将自动作为一个任务加入日程。

   如果所有可等待对象都成功完成，结果将是一个由所有返回值聚合而成的列
   表。结果值的顺序与 *aws* 中可等待对象的顺序一致。

   如果 *return_exceptions* 为 "False" (默认)，所引发的首个异常会立即
   传播给等待 "gather()" 的任务。*aws* 序列中的其他可等待对象 **不会被
   取消** 并将继续运行。

   如果 *return_exceptions* 为 "True"，异常会和成功的结果一样处理，并
   聚合至结果列表。

   如果 "gather()" *被取消*，所有被提交 (尚未完成) 的可等待对象也会 *
   被取消*。

   如果 *aws* 序列中的任一 Task 或 Future 对象 *被取消*，它将被当作引
   发了 "CancelledError" 一样处理 -- 在此情况下 "gather()" 调用 **不会
   ** 被取消。这是为了防止一个已提交的 Task/Future 被取消导致其他
   Tasks/Future 也被取消。

   Deprecated since version 3.8, will be removed in version 3.10:
   *loop* 形参。

   示例:

      import asyncio

      async def factorial(name, number):
          f = 1
          for i in range(2, number + 1):
              print(f"Task {name}: Compute factorial({i})...")
              await asyncio.sleep(1)
              f *= i
          print(f"Task {name}: factorial({number}) = {f}")

      async def main():
          # Schedule three calls *concurrently*:
          await asyncio.gather(
              factorial("A", 2),
              factorial("B", 3),
              factorial("C", 4),
          )

      asyncio.run(main())

      # Expected output:
      #
      #     Task A: Compute factorial(2)...
      #     Task B: Compute factorial(2)...
      #     Task C: Compute factorial(2)...
      #     Task A: factorial(2) = 2
      #     Task B: Compute factorial(3)...
      #     Task C: Compute factorial(3)...
      #     Task B: factorial(3) = 6
      #     Task C: Compute factorial(4)...
      #     Task C: factorial(4) = 24

   備註:

     如果 *return_exceptions* 为 False，则在 gather() 被标记为已完成后
     取消它将不会取消任何已提交的可等待对象。 例如，在将一个异常传播给
     调用者之后，gather 可被标记为已完成，因此，在从 gather 捕获一个（
     由可等待对象所引发的）异常之后调用 "gather.cancel()" 将不会取消任
     何其他可等待对象。

   3.7 版更變: 如果 *gather* 本身被取消，则无论 *return_exceptions* 取
   值为何，消息都会被传播。


屏蔽取消操作
============

awaitable asyncio.shield(aw, *, loop=None)

   保护一个 可等待对象 防止其被 "取消"。

   如果 *aw* 是一个协程，它将自动作为任务加入日程。

   以下语句:

      res = await shield(something())

   相当于:

      res = await something()

   *不同之处* 在于如果包含它的协程被取消，在 "something()" 中运行的任
   务不会被取消。从 "something()" 的角度看来，取消操作并没有发生。然而
   其调用者已被取消，因此 "await" 表达式仍然会引发 "CancelledError"。

   如果通过其他方式取消 "something()" (例如在其内部操作) 则 "shield()"
   也会取消。

   如果希望完全忽略取消操作 (不推荐) 则 "shield()" 函数需要配合一个
   try/except 代码段，如下所示:

      try:
          res = await shield(something())
      except CancelledError:
          res = None

   Deprecated since version 3.8, will be removed in version 3.10:
   *loop* 形参。


超时
====

coroutine asyncio.wait_for(aw, timeout, *, loop=None)

   等待 *aw* 可等待对象 完成，指定 timeout 秒数后超时。

   如果 *aw* 是一个协程，它将自动作为任务加入日程。

   *timeout* 可以为 "None"，也可以为 float 或 int 型数值表示的等待秒数
   。如果 *timeout* 为 "None"，则等待直到完成。

   如果发生超时，任务将取消并引发 "asyncio.TimeoutError".

   要避免任务 "取消"，可以加上 "shield()"。

   函数将等待直到目标对象确实被取消，所以总等待时间可能超过 *timeout*
   指定的秒数。

   如果等待被取消，则 *aw* 指定的对象也会被取消。

   Deprecated since version 3.8, will be removed in version 3.10:
   *loop* 形参。

   示例:

      async def eternity():
          # Sleep for one hour
          await asyncio.sleep(3600)
          print('yay!')

      async def main():
          # Wait for at most 1 second
          try:
              await asyncio.wait_for(eternity(), timeout=1.0)
          except asyncio.TimeoutError:
              print('timeout!')

      asyncio.run(main())

      # Expected output:
      #
      #     timeout!

   3.7 版更變: 当 *aw* 因超时被取消，"wait_for" 会等待 *aw* 被取消。之
   前版本则将立即引发 "asyncio.TimeoutError"。


简单等待
========

coroutine asyncio.wait(aws, *, loop=None, timeout=None, return_when=ALL_COMPLETED)

   Run awaitable objects in the *aws* iterable concurrently and block
   until the condition specified by *return_when*.

   返回两个 Task/Future 集合: "(done, pending)"。

   用法:

      done, pending = await asyncio.wait(aws)

   如指定 *timeout* (float 或 int 类型) 则它将被用于控制返回之前等待的
   最长秒数。

   请注意此函数不会引发 "asyncio.TimeoutError"。当超时发生时，未完成的
   Future 或 Task 将在指定秒数后被返回。

   *return_when* 指定此函数应在何时返回。它必须为以下常数之一:

   +-------------------------------+------------------------------------------+
   | 常数                          | 描述                                     |
   |===============================|==========================================|
   | "FIRST_COMPLETED"             | 函数将在任意可等待对象结束或取消时返回。 |
   +-------------------------------+------------------------------------------+
   | "FIRST_EXCEPTION"             | 函数将在任意可等待对象因引发异常而结束时 |
   |                               | 返回。当没有引发任何异常时 它就相当于    |
   |                               | "ALL_COMPLETED"。                        |
   +-------------------------------+------------------------------------------+
   | "ALL_COMPLETED"               | 函数将在所有可等待对象结束或取消时返回。 |
   +-------------------------------+------------------------------------------+

   与 "wait_for()" 不同，"wait()" 在超时发生时不会取消可等待对象。

   3.8 版後已棄用: 如果 *aws* 中的某个可等待对象为协程，它将自动作为任
   务加入日程。直接向 "wait()" 传入协程对象已弃用，因为这会导致 令人迷
   惑的行为。

   Deprecated since version 3.8, will be removed in version 3.10:
   *loop* 形参。

   備註:

     "wait()" 会自动将协程作为任务加入日程，以后将以 "(done, pending)"
     集合形式返回显式创建的任务对象。因此以下代码并不会有预期的行为:

        async def foo():
            return 42

        coro = foo()
        done, pending = await asyncio.wait({coro})

        if coro in done:
            # This branch will never be run!

     以上代码段的修正方法如下:

        async def foo():
            return 42

        task = asyncio.create_task(foo())
        done, pending = await asyncio.wait({task})

        if task in done:
            # Everything will work as expected now.

   3.8 版後已棄用: 直接向 "wait()" 传入协程对象的方式已弃用。

asyncio.as_completed(aws, *, loop=None, timeout=None)

   Run awaitable objects in the *aws* iterable concurrently.  Return
   an iterator of coroutines. Each coroutine returned can be awaited
   to get the earliest next result from the iterable of the remaining
   awaitables.

   如果在所有 Future 对象完成前发生超时则将引发 "asyncio.TimeoutError"
   。

   Deprecated since version 3.8, will be removed in version 3.10:
   *loop* 形参。

   示例:

      for coro in as_completed(aws):
          earliest_result = await coro
          # ...


来自其他线程的日程安排
======================

asyncio.run_coroutine_threadsafe(coro, loop)

   向指定事件循环提交一个协程。线程安全。

   返回一个 "concurrent.futures.Future" 以等待来自其他 OS 线程的结果。

   此函数应该从另一个 OS 线程中调用，而非事件循环运行所在线程。示例:

      # Create a coroutine
      coro = asyncio.sleep(1, result=3)

      # Submit the coroutine to a given loop
      future = asyncio.run_coroutine_threadsafe(coro, loop)

      # Wait for the result with an optional timeout argument
      assert future.result(timeout) == 3

   如果在协程内产生了异常，将会通知返回的 Future 对象。它也可被用来取
   消事件循环中的任务:

      try:
          result = future.result(timeout)
      except asyncio.TimeoutError:
          print('The coroutine took too long, cancelling the task...')
          future.cancel()
      except Exception as exc:
          print(f'The coroutine raised an exception: {exc!r}')
      else:
          print(f'The coroutine returned: {result!r}')

   参见 concurrency and multithreading 部分的文档。

   不同与其他 asyncio 函数，此函数要求显式地传入 *loop* 参数。

   3.5.1 版新加入.


内省
====

asyncio.current_task(loop=None)

   返回当前运行的 "Task" 实例，如果没有正在运行的任务则返回 "None"。

   如果 *loop* 为 "None" 则会使用 "get_running_loop()" 获取当前事件循
   环。

   3.7 版新加入.

asyncio.all_tasks(loop=None)

   返回事件循环所运行的未完成的 "Task" 对象的集合。

   如果 *loop* 为 "None"，则会使用 "get_running_loop()" 获取当前事件循
   环。

   3.7 版新加入.


Task 对象
=========

class asyncio.Task(coro, *, loop=None, name=None)

   一个与 "Future 类似" 的对象，可运行 Python 协程。非线程安全。

   Task 对象被用来在事件循环中运行协程。如果一个协程在等待一个 Future
   对象，Task 对象会挂起该协程的执行并等待该 Future 对象完成。当该
   Future 对象 *完成*，被打包的协程将恢复执行。

   事件循环使用协同日程调度: 一个事件循环每次运行一个 Task 对象。而一
   个 Task 对象会等待一个 Future 对象完成，该事件循环会运行其他 Task、
   回调或执行 IO 操作。

   使用高层级的 "asyncio.create_task()" 函数来创建 Task 对象，也可用低
   层级的 "loop.create_task()" 或 "ensure_future()" 函数。不建议手动实
   例化 Task 对象。

   要取消一个正在运行的 Task 对象可使用 "cancel()" 方法。调用此方法将
   使该 Task 对象抛出一个 "CancelledError" 异常给打包的协程。如果取消
   期间一个协程正在等待一个 Future 对象，该 Future 对象也将被取消。

   "cancelled()" 可被用来检测 Task 对象是否被取消。如果打包的协程没有
   抑制 "CancelledError" 异常并且确实被取消，该方法将返回 "True"。

   "asyncio.Task" 从 "Future" 继承了其除 "Future.set_result()" 和
   "Future.set_exception()" 以外的所有 API。

   Task 对象支持 "contextvars" 模块。当一个 Task 对象被创建，它将复制
   当前上下文，然后在复制的上下文中运行其协程。

   3.7 版更變: 加入对 "contextvars" 模块的支持。

   3.8 版更變: 添加了 "name" 形参。

   Deprecated since version 3.8, will be removed in version 3.10:
   *loop* 形参。

   cancel()

      请求取消 Task 对象。

      这将安排在下一轮事件循环中抛出一个 "CancelledError" 异常给被封包
      的协程。

      协程在之后有机会进行清理甚至使用 "try" ... ... "except
      CancelledError" ... "finally" 代码块抑制异常来拒绝请求。不同于
      "Future.cancel()"，"Task.cancel()" 不保证 Task 会被取消，虽然抑
      制完全取消并不常见，也很不鼓励这样做。

      以下示例演示了协程是如何侦听取消请求的:

         async def cancel_me():
             print('cancel_me(): before sleep')

             try:
                 # Wait for 1 hour
                 await asyncio.sleep(3600)
             except asyncio.CancelledError:
                 print('cancel_me(): cancel sleep')
                 raise
             finally:
                 print('cancel_me(): after sleep')

         async def main():
             # Create a "cancel_me" Task
             task = asyncio.create_task(cancel_me())

             # Wait for 1 second
             await asyncio.sleep(1)

             task.cancel()
             try:
                 await task
             except asyncio.CancelledError:
                 print("main(): cancel_me is cancelled now")

         asyncio.run(main())

         # Expected output:
         #
         #     cancel_me(): before sleep
         #     cancel_me(): cancel sleep
         #     cancel_me(): after sleep
         #     main(): cancel_me is cancelled now

   cancelled()

      如果 Task 对象 *被取消* 则返回 "True"。

      当使用 "cancel()" 发出取消请求时 Task 会被 *取消*，其封包的协程
      将传播被抛入的 "CancelledError" 异常。

   done()

      如果 Task 对象 *已完成* 则返回 "True"。

      当 Task 所封包的协程返回一个值、引发一个异常或 Task 本身被取消时
      ，则会被认为 *已完成*。

   result()

      返回 Task 的结果。

      如果 Task 对象 *已完成*，其封包的协程的结果会被返回 (或者当协程
      引发异常时，该异常会被重新引发。)

      如果 Task 对象 *被取消*，此方法会引发一个 "CancelledError" 异常
      。

      如果 Task 对象的结果还不可用，此方法会引发一个
      "InvalidStateError" 异常。

   exception()

      返回 Task 对象的异常。

      如果所封包的协程引发了一个异常，该异常将被返回。如果所封包的协程
      正常返回则该方法将返回 "None"。

      如果 Task 对象 *被取消*，此方法会引发一个 "CancelledError" 异常
      。

      如果 Task 对象尚未 *完成*，此方法将引发一个 "InvalidStateError"
      异常。

   add_done_callback(callback, *, context=None)

      添加一个回调，将在 Task 对象 *完成* 时被运行。

      此方法应该仅在低层级的基于回调的代码中使用。

      要了解更多细节请查看 "Future.add_done_callback()" 的文档。

   remove_done_callback(callback)

      从回调列表中移除 *callback* 。

      此方法应该仅在低层级的基于回调的代码中使用。

      要了解更多细节请查看 "Future.remove_done_callback()" 的文档。

   get_stack(*, limit=None)

      返回此 Task 对象的栈框架列表。

      如果所封包的协程未完成，这将返回其挂起所在的栈。如果协程已成功完
      成或被取消，这将返回一个空列表。如果协程被一个异常终止，这将返回
      回溯框架列表。

      框架总是从按从旧到新排序。

      每个被挂起的协程只返回一个栈框架。

      可选的 *limit* 参数指定返回框架的数量上限；默认返回所有框架。返
      回列表的顺序要看是返回一个栈还是一个回溯：栈返回最新的框架，回溯
      返回最旧的框架。(这与 traceback 模块的行为保持一致。)

   print_stack(*, limit=None, file=None)

      打印此 Task 对象的栈或回溯。

      此方法产生的输出类似于 traceback 模块通过 "get_stack()" 所获取的
      框架。

      *limit* 参数会直接传递给 "get_stack()"。

      *file* 参数是输出所写入的 I/O 流；默认情况下输出会写入
      "sys.stderr"。

   get_coro()

      返回由 "Task" 包装的协程对象。

      3.8 版新加入.

   get_name()

      返回 Task 的名称。

      如果没有一个 Task 名称被显式地赋值，默认的 asyncio Task 实现会在
      实例化期间生成一个默认名称。

      3.8 版新加入.

   set_name(value)

      设置 Task 的名称。

      *value* 参数可以为任意对象，它随后会被转换为字符串。

      在默认的 Task 实现中，名称将在任务对象的 "repr()" 输出中可见。

      3.8 版新加入.

   classmethod all_tasks(loop=None)

      返回一个事件循环中所有任务的集合。

      默认情况下将返回当前事件循环中所有任务。如果 *loop* 为 "None"，
      则会使用 "get_event_loop()" 函数来获取当前事件循环。

      Deprecated since version 3.7, will be removed in version 3.9: 请
      不要将此方法作为任务方法来调用。 应当改用 "asyncio.all_tasks()"
      函数。

   classmethod current_task(loop=None)

      返回当前运行任务或 "None"。

      如果 *loop* 为 "None"，则会使用 "get_event_loop()" 函数来获取当
      前事件循环。

      Deprecated since version 3.7, will be removed in version 3.9: 请
      不要将此方法作为任务方法来调用。 应当改用
      "asyncio.current_task()" 函数。


基于生成器的协程
================

備註:

  对基于生成器的协程的支持 **已弃用** 并计划在 Python 3.10 中移除。

基于生成器的协程是 async/await 语法的前身。它们是使用 "yield from" 语
句创建的 Python 生成器，可以等待 Future 和其他协程。

基于生成器的协程应该使用 "@asyncio.coroutine" 装饰，虽然这并非强制。

@asyncio.coroutine

   用来标记基于生成器的协程的装饰器。

   此装饰器使得旧式的基于生成器的协程能与 async/await 代码相兼容:

      @asyncio.coroutine
      def old_style_coroutine():
          yield from asyncio.sleep(1)

      async def main():
          await old_style_coroutine()

   此装饰器不应该被用于 "async def" 协程。

   Deprecated since version 3.8, will be removed in version 3.10: 请改
   用 "async def"。

asyncio.iscoroutine(obj)

   如果 *obj* 是一个 协程对象 则返回 "True"。

   此方法不同于 "inspect.iscoroutine()" 因为它对基于生成器的协程返回
   "True"。

asyncio.iscoroutinefunction(func)

   如果 *func* 是一个 协程函数 则返回 "True"。

   此方法不同于 "inspect.iscoroutinefunction()" 因为它对以
   "@coroutine" 装饰的基于生成器的协程函数返回 "True"。
