状态

一个参考实现存在于代码名称 Tulip 下。Tulip 仓库链接在最后的参考文献部分。基于此仓库的包将提供在 PyPI 上（见参考文献），以使用 asyncio 包与 Python 3.3 安装一起使用。

截至 2013 年 10 月 20 日，asyncio 包已签入 Python 3.4 存储库，并与 Python 3.4-alpha-4 一起发布，具有“临时”API 状态。这是对信心的表达，旨在增加对 API 的早期反馈，而不是强迫接受 PEP。预期该包将在 Python 3.4 中保持临时状态，并在 Python 3.5 中进展到最终状态。开发继续主要在 Tulip 仓库中进行，偶尔会将更改合并到 CPython 仓库中。

依赖

Python 3.3 是许多提议功能所必需的。参考实现（Tulip）除了 Python 3.3 之外不需要任何新的语言或标准库功能，不需要任何第三方模块或包，也不需要任何 C 代码，除了 Windows 上的（可选）IOCP 支持。

模块命名空间

此处的规范位于一个新的顶级包 asyncio 中。不同的组件位于包的独立子模块中。该包将从其各自的子模块导入常见的 API，并将它们作为包属性提供（类似于电子邮件包的工作方式）。对于此类常见的 API，实际定义它们的子模块名称不是规范的一部分。不太常见的 API 可能需要显式地从其各自的子模块导入，在这种情况下，子模块名称是规范的一部分。

在没有子模块名称的情况下定义的类和函数假定位于顶级包的命名空间中。（但不要将这些与各种类的​​方法混淆，这些方法出于简洁考虑，在某些情况下也无需命名空间前缀。）

互操作性

事件循环是大多数互操作性发生的地方。对于（Python 3.3 端口）像 Twisted、Tornado 甚至 gevents 这样的框架，应该很容易通过使用轻量级适配器或代理来适应默认的事件循环实现以满足其需求，或者用他们自己的事件循环实现的改编来替换默认的事件循环实现。（一些框架，如 Twisted，有多个事件循环实现。这应该不是问题，因为它们都有相同的接口。）

在大多数情况下，两个不同的第三方框架应该能够相互操作，要么通过共享默认的事件循环实现（每个框架使用自己的适配器），要么通过共享任一框架的事件循环实现。在后一种情况下，将发生两级适配（从框架 A 的事件循环到标准事件循环接口，再从那里到框架 B 的事件循环）。使用哪个事件循环实现应该由主程序控制（尽管提供了一个用于事件循环选择的默认策略）。

为了使这种互操作性有效，第三方框架中首选的适配方向是保留默认的事件循环并将其适应框架的 API。理想情况下，所有第三方框架都会放弃自己的事件循环实现，转而使用标准实现。但并非所有框架都能满足标准实现提供的功能。

为了支持双向适配，指定了两个独立的 API

• 用于管理当前事件循环的接口
• 符合的事件循环的接口

事件循环实现可以提供其他方法和保证，只要这些方法在文档中被调用为非标准方法。事件循环实现也可以省略某些方法，如果它们无法在给定的环境中实现；但是，此类与标准 API 的偏差应仅被视为最后的手段，并且仅当平台或环境强制执行时。（一个例子是在存在无法启动或停止的系统事件循环的平台上；参见下面的“嵌入式事件循环”。）

事件循环 API 不依赖于 await/yield from。相反，它使用回调、附加接口（传输和协议）以及期货的组合。后者类似于 PEP 3148 中定义的期货，但具有不同的实现，并且不与线程绑定。特别是，result() 方法在结果尚未准备好时会抛出异常，而不是阻塞；预计用户将使用回调（或 await/yield from）等待结果。

对于所有指定为返回协程的事件循环方法，允许它们返回期货或协程，由实现选择（标准实现始终返回协程）。所有记录为接受协程参数的事件循环方法必须接受此类参数的期货和协程。（一个便利函数，ensure_future()，存在于将协程或期货参数转换为期货。）

对于不喜欢使用回调的用户（像我一样），提供了一个调度程序，用于使用 PEP 380 yield from 或 PEP 492 await 表达式将异步 I/O 代码编写为协程。调度程序不可插拔；可插拔性发生在事件循环级别，标准调度程序实现应该与任何符合的事件循环实现一起工作。（事实上，这是一个重要的检验符合实现的标准。）

为了在使用协程编写的代码和其他异步框架之间进行互操作，调度程序定义了一个 Task 类，其行为类似于期货。与事件循环级别进行互操作的框架可以通过向期货添加回调来等待期货完成。同样，调度程序提供了一个操作来挂起协程，直到回调被调用。

如果此类框架无法按原样使用期货和 Task 类，则它可以重新实现 loop.create_future() 和 loop.create_task() 方法。这些方法应该返回实现（期货/Task 接口的超集）的对象。

一个不太雄心勃勃的框架可能只会调用 loop.set_task_factory() 来替换 Task 类，而无需实现自己的事件循环。

事件循环 API 为线程提供了有限的互操作性：有一个 API 可以将函数提交给执行器（参见 PEP 3148），该执行器返回一个与事件循环兼容的期货，并且有一个方法可以以线程安全的方式从另一个线程调度事件循环的回调。

传输和协议

对于不熟悉 Twisted 的人，有必要简要解释一下传输和协议之间的关系。在最高级别，传输关注字节如何传输，而协议确定字节哪些传输（以及在某种程度上何时传输）。

另一种说法是：传输是套接字（或类似的 I/O 端点）的抽象，而协议是从传输的角度来看应用程序的抽象。

另一种看法是，传输和协议接口一起定义了使用网络 I/O 和进程间 I/O 的抽象接口。

几乎总是存在传输和协议对象之间的 1:1 关系：协议调用传输方法来发送数据，而传输调用协议方法来传递已接收的数据。传输或协议方法都不会“阻塞”——它们会启动事件，然后返回。

最常见的传输类型是双向流传输。它代表一对缓冲流（每个方向一个），每个流传输一个字节序列。最常见的双向流传输示例可能是 TCP 连接。另一个常见示例是 SSL/TLS 连接。但也有一些其他事物可以这样看待，例如 SSH 会话或一对 UNIX 管道。通常情况下，传输实现并不多，而且大多数传输实现都附带事件循环实现。但是，并非所有传输都必须通过调用事件循环方法来创建：第三方模块可以实现新的传输，并为其提供构造函数或工厂函数，这些函数只需要将事件循环作为参数或调用 get_event_loop()。

注意，传输不需要使用套接字，即使它们使用 TCP 也是如此——套接字是平台特定的实现细节。

双向流传输有两个“端点”：一个端点与网络（或另一个进程，或它包装的任何低级接口）通信，另一个端点与协议通信。前者使用任何必要的 API 来实现传输；但传输和协议之间的接口由本 PEP 标准化。

协议可以表示某种“应用程序级”协议，例如 HTTP 或 SMTP；它也可以实现由多个协议共享的抽象，或整个应用程序。协议的主要接口是与传输的接口。虽然一些流行的协议（和其他抽象）可能具有标准实现，但应用程序通常会实现自定义协议。拥有可从 PyPI 下载和安装的有用第三方协议实现库也很有意义。

传输和协议的通用概念包括其他接口，其中传输包装了一些其他通信抽象。例如，用于发送和接收数据报的接口（例如 UDP），或子进程管理器。关注点的分离与双向流传输和协议相同，但传输和协议之间的特定接口在每种情况下都不同。

各种标准类型的传输和协议定义的接口的详细信息将在后面给出。

事件循环策略：获取和设置当前事件循环

事件循环管理由事件循环策略控制，事件循环策略是一个全局（每个进程）对象。存在默认策略，以及更改策略的 API。策略定义了上下文的概念；策略为每个上下文管理一个独立的事件循环。默认策略的上下文概念定义为当前线程。

某些平台或编程框架可能会将默认策略更改为更适合该平台或框架用户期望的策略。此类平台或框架必须记录其策略以及在初始化序列中的哪个点设置策略，以避免在多个活动框架想要覆盖默认策略时出现未定义的行为。（另请参阅下面的“嵌入式事件循环”。）

要获取当前上下文的事件循环，请使用 get_event_loop()。这将返回一个实现下面指定的接口的事件循环对象，或者如果当前上下文没有设置事件循环且当前策略未指定创建事件循环，则会引发异常。它不应该返回 None。

要为当前上下文设置事件循环，请使用 set_event_loop(event_loop)，其中 event_loop 是一个事件循环对象，即 AbstractEventLoop 的实例，或者 None。将当前事件循环设置为 None 是可以的，在这种情况下，后续对 get_event_loop() 的调用将引发异常。这对于测试不应该依赖于默认事件循环存在的代码很有用。

预期 get_event_loop() 返回一个不同的事件循环对象，具体取决于上下文（实际上，这就是上下文的定义）。如果未设置事件循环并且策略允许创建事件循环，它可能会创建一个新的事件循环对象。默认策略只会在主线程（由 threading.py 定义，它使用特殊子类表示主线程）中创建一个新的事件循环，并且只有在调用 get_event_loop() 之前调用 set_event_loop()。（要重置此状态，请重置策略。）在其他线程中，必须显式设置事件循环。其他策略可能会有不同的行为。默认策略创建的事件循环是惰性的；即对 get_event_loop() 的第一次调用将在必要时并根据当前策略创建事件循环实例。

为了方便单元测试和其他特殊情况，存在第三个策略函数：new_event_loop()，它根据策略的默认规则创建并返回一个新的事件循环对象。要将此事件循环设置为当前事件循环，必须使用它调用 set_event_loop()。

要更改事件循环策略，请调用 set_event_loop_policy(policy)，其中 policy 是一个事件循环策略对象或 None。如果不是 None，则策略对象必须是 AbstractEventLoopPolicy 的实例，该实例定义了方法 get_event_loop()、set_event_loop(loop) 和 new_event_loop()，所有这些方法的行为都与上面描述的函数相同。

传递 None 的策略值将恢复默认事件循环策略（覆盖平台或框架设置的备用默认值）。默认事件循环策略是类 DefaultEventLoopPolicy 的实例。可以通过调用 get_event_loop_policy() 来检索当前事件循环策略对象。

待定：描述子进程处理的子进程监视器和 UNIX quirks。

指定时间

像往常一样，在 Python 中，所有超时、间隔和延迟都以秒为单位，可以是整数或浮点数。但是，绝对时间不会指定为 POSIX 时间戳。时钟的精度、精确度和纪元由实现决定。

默认实现使用 time.monotonic()。关于此选择的影响可以写成书。最好阅读标准库 time 模块的文档。

嵌入式事件循环

在某些平台上，事件循环由系统提供。此类循环可能在用户代码启动时就已经运行，并且可能无法停止或关闭它，除非退出程序。在这种情况下，启动、停止和关闭事件循环的方法可能无法实现，并且 is_running() 可能始终返回 True。

事件循环类

实际上没有名为 EventLoop 的类。存在一个 AbstractEventLoop 类，它定义了所有没有实现的方法，主要用作文档。定义了以下具体类

• SelectorEventLoop 是基于 selectors 模块（Python 3.4 中新增）的完整 API 的具体实现。构造函数接受一个可选参数，即 selectors.Selector 对象。默认情况下，将创建一个 selectors.DefaultSelector 的实例并使用它。
• ProactorEventLoop 是 API 的具体实现，但 I/O 事件处理和信号处理方法除外。它只在 Windows（或支持类似 API 以进行“重叠 I/O”的其他平台）上定义。构造函数接受一个可选参数，即 Proactor 对象。默认情况下，将创建一个 IocpProactor 的实例并使用它。（IocpProactor 类未在本 PEP 中指定；它只是 ProactorEventLoop 类的实现细节。）

事件循环方法概述

符合规范的事件循环的方法分为几类。第一组类别必须由所有符合规范的事件循环实现支持，但嵌入式事件循环可能不会实现启动、停止和关闭方法除外。（但是，部分符合规范的事件循环仍然比没有好。:-)）

• 启动、停止和关闭：run_forever()、run_until_complete()、stop()、is_running()、close()、is_closed()。
• 基本和定时回调：call_soon()、call_later()、call_at()、time()。
• 线程交互：call_soon_threadsafe()、run_in_executor()、set_default_executor()。
• Internet 名称查找：getaddrinfo()、getnameinfo()。
• Internet 连接：create_connection()、create_server()、create_datagram_endpoint()。
• 包装的套接字方法：sock_recv()、sock_sendall()、sock_connect()、sock_accept()。
• 任务和期货支持：create_future()、create_task()、set_task_factory()、get_task_factory()。
• 错误处理：get_exception_handler()、set_exception_handler()、default_exception_handler()、call_exception_handler()。
• 调试模式：get_debug()、set_debug()。

第二组类别可能得到符合的事件循环实现的支持。如果不受支持，它们将引发 NotImplementedError。（在默认实现中，UNIX 系统上的 SelectorEventLoop 支持所有这些；Windows 上的 SelectorEventLoop 支持 I/O 事件处理类别；Windows 上的 ProactorEventLoop 支持管道和子进程类别。）

• I/O 回调：add_reader()、remove_reader()、add_writer()、remove_writer()。
• 管道和子进程：connect_read_pipe()、connect_write_pipe()、subprocess_shell()、subprocess_exec()。
• 信号回调：add_signal_handler()、remove_signal_handler()。

事件循环方法

回调的互斥

事件循环应该强制执行回调的互斥，即它永远不应该在先前回调仍在运行时启动回调。这应该适用于所有类型的回调，无论它们是使用 call_soon()、call_later()、call_at()、call_soon_threadsafe()、add_reader()、add_writer() 或 add_signal_handler() 调度的。

异常

Python 中有两种类型的异常：从 Exception 类派生的异常和从 BaseException 类派生的异常。从 Exception 派生的异常通常会被捕获并适当地处理；例如，它们将被 Futures 传递，并且当它们在回调中发生时，它们将被记录并忽略。

但是，仅从 BaseException 派生的异常通常不会被捕获，并且通常会导致程序以跟踪记录终止。在某些情况下，它们会被捕获并重新引发。（此类别的示例包括 KeyboardInterrupt 和 SystemExit；通常明智的做法是不将它们与大多数其他异常相同对待。）

事件循环将后一类传递到其异常处理程序中。这是一个回调，它接受上下文字典作为参数

def exception_handler(context):
    ...

上下文可能具有许多不同的键，但其中一些被广泛使用

• 'message': 错误消息。
• 'exception': 异常实例；如果不存在异常，则为 None。
• 'source_traceback': 一个字符串列表，表示创建与错误相关的对象的点的堆栈。
• 'handle_traceback': 一个字符串列表，表示创建与错误相关的句柄的时刻的堆栈。

循环具有以下与异常处理相关的 方法

• get_exception_handler() 返回为循环注册的当前异常处理程序。
• set_exception_handler(handler) 设置异常处理程序。
• default_exception_handler(context) 此循环实现的默认异常处理程序。
• call_exception_handler(context) 将上下文传递给已注册的异常处理程序。这允许第三方库统一处理未捕获的异常。

  如果默认值未被显式 set_exception_handler() 调用覆盖，则循环使用 default_exception_handler()。

调试模式

默认情况下，循环在发布模式下运行。应用程序可以通过启用调试模式以更好的错误报告为代价来提高性能。

在调试模式下，将启用许多其他检查，例如

• 源跟踪记录可用于期货/任务中的未处理异常。
• 循环检查缓慢的回调以检测意外的 I/O 阻塞。

  loop.slow_callback_duration 属性控制在两个yield 点之间允许的最大执行时间，在报告缓慢的回调之前。默认值为 0.1 秒；可以通过分配给它来更改它。

有两个与调试模式相关的 方法

• get_debug() 如果启用了调试模式，则返回 True，否则返回 False。
• set_debug(enabled) 如果参数为 True，则启用调试模式。

如果定义了 PYTHONASYNCIODEBUG 环境变量并且它不为空，则会自动启用调试模式。

句柄

注册一次性回调的各种方法（call_soon()、call_later()、call_at() 和 call_soon_threadsafe()）都返回一个表示注册的对象，该对象可用于取消回调。此对象称为 Handle。Handles 是不透明的，只有一个公共方法

• cancel()：取消回调。

请注意，add_reader()、add_writer() 和 add_signal_handler() 不会返回 Handles。

服务器

create_server() 方法返回一个 Server 实例，该实例包装了用于接受请求的套接字（或其他网络对象）。此类有两个公共方法

• close()：关闭服务。这将停止接受新请求，但不会取消已接受并正在处理的请求。
• wait_closed()：一个协程，它阻塞直到服务关闭且所有已接受的请求都已处理。

期货

这里的 asyncio.Future 类有意与 PEP 3148 中指定的 concurrent.futures.Future 类类似，但有一些细微的差别。无论何时本 PEP 谈论 Futures 或 futures，都应理解为是指 asyncio.Future，除非明确提及 concurrent.futures.Future。支持的公共 API 如下所示，指出了与 PEP 3148 的区别

• cancel()。如果 Future 已经完成（或已取消），则不做任何操作并返回 False。否则，这将尝试取消 Future 并返回 True。如果取消尝试成功，最终 Future 的状态将变为取消（以便 cancelled() 将返回 True），并且回调将被调度。对于常规 Futures，取消将始终立即成功；但对于 Tasks（见下文），任务可能会忽略或延迟取消尝试。
• cancelled()。如果 Future 被成功取消，则返回 True。
• done()。如果 Future 完成，则返回 True。请注意，已取消的 Future 也被认为已完成（在此处和所有地方）。
• result()。返回使用 set_result() 设置的结果集，或引发使用 set_exception() 设置的异常。如果取消，则引发 CancelledError。与 PEP 3148 的区别：这没有超时参数并且 *不* 等待；如果 future 尚未完成，它将引发异常。
• exception()。如果使用 set_exception() 设置了异常，则返回该异常，或者如果使用 set_result() 设置了结果，则返回 None。如果取消，则引发 CancelledError。与 PEP 3148 的区别：这没有超时参数并且 *不* 等待；如果 future 尚未完成，它将引发异常。
• add_done_callback(fn)。添加一个回调，在 Future 完成（或被取消）时运行。如果 Future 已经完成（或已取消），则使用 call_soon() 调度回调。与 PEP 3148 的区别：回调永远不会立即调用，并且始终在调用者的上下文中调用 - 通常这是线程。您可以将其视为通过 call_soon() 调用回调。请注意，为了与 PEP 3148 匹配，回调（与本 PEP 中定义的所有其他回调不同，并忽略以下“回调样式”部分中的约定）始终使用单个参数（Future 对象）调用。（严格序列化使用 call_soon() 调度的回调的动机也适用于此。）
• remove_done_callback(fn)。从回调列表中删除参数。此方法未由 PEP 3148 定义。该参数必须等于（使用 ==）传递给 add_done_callback() 的参数。返回回调被移除的次数。
• set_result(result)。Future 必须尚未完成（也未取消）。这使 Future 完成并调度回调。与 PEP 3148 的区别：这是一个公共 API。
• set_exception(exception)。Future 必须尚未完成（也未取消）。这使 Future 完成并调度回调。与 PEP 3148 的区别：这是一个公共 API。

内部方法 set_running_or_notify_cancel() 不受支持；无法设置运行状态。同样，方法 running() 也不受支持。

定义了以下异常

• InvalidStateError。每当 Future 不处于对正在调用的方法可接受的状态时引发（例如，对已经完成的 Future 调用 set_result()，或者对尚未完成的 Future 调用 result()）。
• InvalidTimeoutError。当给出非零 timeout 参数时，由 result() 和 exception() 引发。
• CancelledError。concurrent.futures.CancelledError 的别名。当对已取消的 Future 调用 result() 或 exception() 时引发。
• TimeoutError。concurrent.futures.TimeoutError 的别名。可能会由 run_until_complete() 引发。

Future 在创建时与事件循环相关联。

asyncio.Future 对象对于 concurrent.futures 包中的 wait() 和 as_completed() 函数不可接受。但是，存在类似的 API asyncio.wait() 和 asyncio.as_completed()，如下所述。

asyncio.Future 对象在协程中使用时对 yield from 表达式是可接受的。这是通过 Future 上的 __iter__() 接口实现的。请参见以下“协程和调度程序”部分。

当 Future 被垃圾回收时，如果它具有关联的异常，但从未调用过 result() 或 exception()，则记录异常。（当协程使用 yield from 等待 Future 时，协程恢复后会调用该 Future 的 result() 方法。）

将来（双关语），我们可能会统一 asyncio.Future 和 concurrent.futures.Future，例如，通过向后者添加一个 __iter__() 方法，该方法适用于 yield from。为了防止在尚未完成的 Future 上调用例如 result() 时意外阻塞事件循环，阻塞操作可能会检测到当前线程中是否有活动事件循环，并改为引发异常。但是，当前 PEP 努力不依赖于 Python 3.3 之外的任何内容，因此目前无法更改 concurrent.futures.Future。

有一些与 Futures 相关的公共函数

• asyncio.async(arg)。这将接收一个参数，该参数是协程对象或 Future（即，任何可以使用 yield from 的内容），并返回一个 Future。如果参数是 Future，则返回不变；如果它是协程对象，则将其包装在 Task 中（请记住，Task 是 Future 的子类）。
• asyncio.wrap_future(future)。这将接收一个 PEP 3148 Future（即，concurrent.futures.Future 的实例），并返回一个与事件循环兼容的 Future（即，asyncio.Future 实例）。

传输

传输和协议受 Twisted 和 PEP 3153 的强烈影响。用户很少实现或实例化传输 - 相反，事件循环提供了设置传输的实用程序方法。

传输与协议协同工作。协议通常在不知道或不关心所用传输的具体类型的情况下编写，并且传输可以与各种协议一起使用。例如，HTTP 客户端协议实现可以使用普通套接字传输或 SSL/TLS 传输。普通套接字传输除了 HTTP 外，还可以与许多不同的协议一起使用（例如 SMTP、IMAP、POP、FTP、IRC、SPDY）。

最常见的传输类型是双向流传输。还存在单向流传输（用于管道）和数据报传输（由 create_datagram_endpoint() 方法使用）。

协议

协议始终与传输一起使用。虽然提供了一些常见的协议（例如，相当不错但未必优秀的 HTTP 客户端和服务器实现），但大多数协议将由用户代码或第三方库实现。

与传输类似，我们区分流协议、数据报协议，以及其他自定义协议。最常见的协议类型是双向流协议。（没有单向协议。）

回调风格

大多数接受回调的接口也接受位置参数。例如，要安排 foo("abc", 42) 尽快调用，您可以调用 loop.call_soon(foo, "abc", 42)。要安排调用 foo()，请使用 loop.call_soon(foo)。此约定极大地减少了典型回调编程中所需的少量 lambda 的数量。

此约定专门 *不支持* 关键字参数。关键字参数用于传递有关回调的可选额外信息。这允许 API 优雅地演进，而不必担心关键字是否对某个地方的被调用者具有重要意义。如果您有一个 *必须* 使用关键字参数调用的回调，可以使用 lambda。例如

loop.call_soon(lambda: foo('abc', repeat=42))

协程

协程是一个遵循某些约定的生成器。出于文档目的，所有协程都应该用 @asyncio.coroutine 装饰，但这无法严格强制执行。

协程使用 PEP 380 中引入的 yield from 语法，而不是原始的 yield 语法。

“协程”一词，与“生成器”一词一样，用于两个不同的（但相关的）概念

• 定义协程的函数（用 asyncio.coroutine 装饰的函数定义）。如果需要消除歧义，我们将称之为 *协程函数*。
• 通过调用协程函数获得的对象。此对象表示最终将完成的计算或 I/O 操作（通常是两者兼而有之）。如果需要消除歧义，我们将称之为 *协程对象*。

协程可以做的事情

• result = yield from future – 暂停协程，直到期货完成，然后返回期货的结果，或者引发一个异常，该异常将被传播。（如果期货被取消，它将引发一个 CancelledError 异常。）请注意，任务是期货，关于期货的所有内容也适用于任务。
• result = yield from coroutine – 等待另一个协程生成结果（或引发一个异常，该异常将被传播）。coroutine 表达式必须是另一个协程的 *调用*。
• return expression – 向正在使用 yield from 等待此协程的协程生成结果。
• raise exception – 使用 yield from 在等待此协程的协程中引发异常。

调用协程不会立即启动其代码运行 - 它只是一个生成器，调用返回的协程对象实际上是一个生成器对象，在你对其进行迭代之前它不会执行任何操作。对于协程对象，有两种基本方法可以启动它的运行：从另一个协程调用 yield from coroutine（假设另一个协程已经在运行！），或者将其转换为 Task（见下文）。

协程（和任务）只有在事件循环正在运行时才能运行。

等待多个协程

要等待多个协程或 Futures，提供了两个类似于 concurrent.futures 包中的 wait() 和 as_completed() API 的 API

• asyncio.wait(fs, timeout=None, return_when=ALL_COMPLETED)。这是一个协程，它等待由 fs 给出的 Futures 或协程完成。协程参数将被包装在 Tasks 中（见下文）。它返回一个 Future，其成功的结果是一个包含两个 Futures 集合的元组，(done, pending)，其中 done 是已完成（或已取消）的原始 Futures（或包装的协程）的集合，而 pending 是其余的，即那些尚未完成（或尚未取消）的。请注意，使用 timeout 和 return_when 的默认值，done 将始终是一个空列表。可选参数 timeout 和 return_when 的含义和默认值与 concurrent.futures.wait() 相同：timeout，如果非 None，则指定整个操作的超时时间；return_when 指定何时停止。常量 FIRST_COMPLETED、FIRST_EXCEPTION、ALL_COMPLETED 的定义值和含义与 PEP 3148 中的相同
  • ALL_COMPLETED（默认）：等待所有 Futures 完成（或直到超时发生）。
  • FIRST_COMPLETED：等待至少一个 Future 完成（或直到超时发生）。
  • FIRST_EXCEPTION：等待至少一个 Future 完成但未被取消，并且设置了异常。（从条件中排除已取消的 Futures 令人惊讶，但 PEP 3148 这样做。）
• asyncio.as_completed(fs, timeout=None)。返回一个迭代器，其值为 Futures 或协程；等待连续的值将等待直到来自集合 fs 的下一个 Future 或协程完成，并返回其结果（或引发其异常）。可选参数 timeout 的含义和默认值与 concurrent.futures.wait() 相同：当超时发生时，迭代器返回的下一个 Future 将在等待时引发 TimeoutError。使用示例

  for f in as_completed(fs):
      result = yield from f  # May raise an exception.
      # Use result.
  

  注意：如果你不等待迭代器产生的值，你的 for 循环可能无法取得进展（因为你没有让其他任务运行）。

• asyncio.wait_for(f, timeout)。这是一种方便的方法，用于等待单个协程或 Future 超时。当超时发生时，它会取消任务并引发 TimeoutError。要避免任务取消，请将其包装在 shield() 中。
• asyncio.gather(f1, f2, ...)。返回一个 Future，它将等待所有参数（Futures 或协程）完成并返回其对应结果的列表。如果一个或多个参数被取消或引发异常，返回的 Future 将被取消或设置其异常（与第一个参数发生的情况匹配），而其余参数将在后台继续运行。取消返回的 Future 不会影响参数。请注意，协程参数使用 asyncio.async() 转换为 Futures。
• asyncio.shield(f)。等待一个 Future，使其免受取消的影响。这将返回一个 Future，其结果或异常与参数完全相同；但是，如果返回的 Future 被取消，参数 Future 不会受到影响。

  此函数的一个用例将是一个协程，它为处理 HTTP 服务器中请求的协程缓存查询结果。当客户端取消请求时，我们可能（可以说）希望查询缓存协程继续运行，这样当客户端重新连接时，查询结果（希望）会被缓存。这可以这样编写，例如：

  @asyncio.coroutine
  def handle_request(self, request):
      ...
      cached_query = self.get_cache(...)
      if cached_query is None:
          cached_query = yield from asyncio.shield(self.fill_cache(...))
      ...
  

睡眠

协程 asyncio.sleep(delay) 在给定的时间延迟后返回。

任务

Task 是一个管理独立运行的协程的对象。Task 接口与 Future 接口相同，实际上 Task 是 Future 的子类。当它的协程返回或引发异常时，任务将完成；如果它返回一个结果，该结果将成为任务的结果，如果它引发一个异常，该异常将成为任务的异常。

取消尚未完成的任务会向协程抛出一个 asyncio.CancelledError 异常。如果协程没有捕获它（或者如果它重新引发它），任务将被标记为已取消（即，cancelled() 将返回 True）；但如果协程以某种方式捕获并忽略了异常，它可能会继续执行（并且 cancelled() 将返回 False）。

任务对于协程和基于回调的框架（如 Twisted）之间的互操作也很有用。在将协程转换为 Task 后，可以向 Task 添加回调。

要将协程转换为任务，请调用协程函数并将生成的协程对象传递给 loop.create_task() 方法。你也可以为此目的使用 asyncio.ensure_future()。

你可能会问，为什么不自动将所有协程转换为 Tasks？@asyncio.coroutine 装饰器可以做到这一点。但是，这会大大降低一个协程调用另一个协程（等等）的情况下的速度，因为切换到“裸”协程的开销远小于切换到 Task。

Task 类派生自 Future，添加了新方法

• current_task(loop=None)。一个类方法，返回事件循环中当前正在运行的任务。如果loop 为 None，该方法将返回默认循环的当前任务。每个协程都在一个任务上下文中执行，无论是使用 ensure_future() 或 loop.create_task() 创建的 Task，还是通过使用 yield from 或 await 从另一个协程调用。此方法在协程外部调用时（例如，在使用 loop.call_later() 调度的回调中）返回 None。
• all_tasks(loop=None)。一个类方法，返回循环的所有活动任务的集合。如果loop 为 None，则使用默认循环。

调度程序

调度程序没有公开接口。你可以通过使用 yield from future 和 yield from task 与它交互。事实上，没有一个单独的对象代表调度程序 - 它的行为是由 Task 和 Future 类使用事件循环的公开接口实现的，因此它也适用于第三方事件循环实现。

实用工具

提供了一些函数和类来简化基本的基于流的客户端和服务器（如 FTP 或 HTTP）的编写，例如

• asyncio.open_connection(host, port)：EventLoop.create_connection() 的包装器，不需要你提供 Protocol 工厂或类。这是一个协程，它返回一个 (reader, writer) 对，其中 reader 是 StreamReader 的实例，而 writer 是 StreamWriter 的实例（两者都在下面描述）。
• asyncio.start_server(client_connected_cb, host, port): 是一个用于 EventLoop.create_server() 的包装器，它接受一个简单的回调函数，而不是一个 Protocol 工厂或类。这是一个协程，它返回一个 Server 对象，就像 create_server() 一样。每次接受客户端连接时，都会调用 client_connected_cb(reader, writer)，其中 reader 是 StreamReader 的实例，而 writer 是 StreamWriter 的实例（下面都会描述）。如果 client_connected_cb() 返回的结果是一个协程，它会自动包装在一个 Task 中。
• StreamReader: 一个提供类似于只读二进制流的接口的类，除了各种读取方法都是协程之外。它通常由一个 StreamReaderProtocol 实例驱动。请注意，应该只有一个读取器。读取器的接口是
  • readline(): 一个协程，它读取一个表示以 '\n' 结尾的文本行或直到流结束的字节字符串，以先到者为准。
  • read(n): 一个协程，它最多读取 n 个字节。如果省略或为负数，则读取到流的末尾。
  • readexactly(n): 一个协程，它精确读取 n 个字节，或直到流的末尾，以先到者为准。
  • exception(): 返回使用 set_exception() 在流上设置的异常，或者如果没有设置异常则返回 None。

  驱动程序的接口是

  • feed_data(data): 将 data（一个 bytes 对象）追加到内部缓冲区。如果它提供了足够的数据来满足读取器的协议，这将解除阻塞的读取协程。
  • feed_eof(): 信号缓冲区的末尾。这将解除阻塞的读取协程。在此调用之后，不应再向读取器提供任何数据。
  • set_exception(exc): 在流上设置异常。所有后续读取方法都将引发此异常。在此调用之后，不应再向读取器提供任何数据。
• StreamWriter: 一个提供类似于只写二进制流的接口的类。它包装了一个传输。该接口是传输接口的扩展子集：以下方法的行为与相应的传输方法相同：write()、writelines()、write_eof()、can_write_eof()、get_extra_info()、close()。请注意，写入方法不是协程（这与传输相同，但与 StreamReader 类不同）。以下方法是除传输接口之外的
  • drain(): 在写入大量数据后，应使用 yield from 调用此方法，以进行流量控制。预期的用途如下

    writer.write(data)
    yield from writer.drain()
    

    请注意，从技术上讲，这不是一个协程：它返回一个 Future 或一个空元组（两者都可以传递给 yield from）。使用此方法是可选的。但是，当不使用它时， StreamWriter 下面的传输的内部缓冲区可能会填满所有写入写入器的数据。如果一个应用程序没有对写入的数据量有严格的限制，它应该偶尔调用 yield from drain() 以避免填满传输缓冲区。

• StreamReaderProtocol: 一个协议实现，用作双向流传输/协议接口与 StreamReader 和 StreamWriter 类之间的适配器。它充当特定 StreamReader 实例的驱动程序，响应各种协议回调调用其方法 feed_data()、feed_eof() 和 set_exception()。它还控制 StreamWriter 实例的 drain() 方法的行为。

锁

以下类由 asyncio.locks 提供。对于除 Event 之外的所有这些，with 语句可以与 yield from 结合使用以获取锁并确保无论如何离开 with 块都会释放锁，如下所示

with (yield from my_lock):
    ...

• Lock: 一个基本互斥锁，具有方法 acquire()（一个协程）、locked() 和 release()。
• Event: 一个事件变量，具有方法 wait()（一个协程）、set()、clear() 和 is_set()。
• Condition: 一个条件变量，具有方法 acquire()、wait()、wait_for(predicate)（全部三个协程）、locked()、release()、notify() 和 notify_all()。
• Semaphore: 一个信号量，具有方法 acquire()（一个协程）、locked() 和 release()。构造函数参数是初始值（默认值为 1）。
• BoundedSemaphore: 一个有界信号量；这类似于 Semaphore，但初始值也是最大值。

队列

以下类和异常由 asyncio.queues 提供。

• Queue: 一个标准队列，具有方法 get()、put()（都是协程）、get_nowait()、put_nowait()、empty()、full()、qsize() 和 maxsize()。
• PriorityQueue: Queue 的子类，它按优先级顺序检索条目（最低优先级排在最前面）。
• LifoQueue: Queue 的子类，它首先检索最近添加的条目。
• JoinableQueue: Queue 的子类，具有 task_done() 和 join() 方法（后者是一个协程）。
• Empty、Full: 当分别在空或满的队列上调用 get_nowait() 或 put_nowait() 时引发的异常。

日志记录

asyncio 包执行的所有日志记录都使用单个 logging.Logger 对象， asyncio.logger。要自定义日志记录，可以使用此对象上的标准 Logger API。（但不要替换该对象。）

SIGCHLD 处理在 UNIX 上

在子进程协议中高效地实现 process_exited() 方法需要一个 SIGCHLD 信号处理程序。但是，信号处理程序只能设置在与主线程关联的事件循环上。为了支持从运行在其他线程中的事件循环中生成子进程，存在一种机制允许在多个事件循环之间共享 SIGCHLD 处理程序。有两个额外的函数，asyncio.get_child_watcher() 和 asyncio.set_child_watcher()，以及事件循环策略上的对应方法。

有两个子进程观察器实现类，FastChildWatcher 和 SafeChildWatcher。两者都使用 SIGCHLD。 SafeChildWatcher 类是默认使用的；当同时存在许多子进程时，它效率低下。 FastChildWatcher 类效率很高，但它可能会干扰其他生成子进程的代码（无论是 C 代码还是 Python 代码），而这些代码没有使用 asyncio 事件循环。如果你确定没有使用其他生成子进程的代码，要使用快速实现，请在你的主线程中运行以下代码

watcher = asyncio.FastChildWatcher()
asyncio.set_child_watcher(watcher)