状态

存在一个代号为Tulip的参考实现。Tulip仓库的链接在末尾的参考文献部分。基于此仓库的包将在PyPI上提供（参见参考文献），以便在Python 3.3安装中使用asyncio包。

截至2013年10月20日，asyncio包已提交到Python 3.4仓库，并随Python 3.4-alpha-4发布，API状态为“ provisional”（临时）。这表达了信心并旨在增加对API的早期反馈，而不是强制接受PEP。预计该包在Python 3.4中将保持临时状态，并在Python 3.5中进展到最终状态。开发仍主要在Tulip仓库中进行，偶尔会将更改合并到CPython仓库。

依赖

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

模块命名空间

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

没有子模块名称定义的类和函数被认为存在于顶级包的命名空间中。（但不要将这些与各种类的方法混淆，为了简洁起见，在某些上下文中也无需命名空间前缀使用它们。）

互操作性

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

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

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

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

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

事件循环实现可以提供额外的方法和保证，只要这些在文档中被标记为非标准。事件循环实现也可以在给定环境中无法实现某些方法时将其留空；然而，此类偏离标准API的行为应仅作为最后手段考虑，并且仅当平台或环境强制要求时。（一个例子是无法启动或停止系统事件循环的平台；参见下面的“嵌入式事件循环”。）

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

所有指定返回协程的事件循环方法都允许返回Future或协程，由实现选择（标准实现总是返回协程）。所有文档中接受协程参数的事件循环方法*必须*接受Future和协程作为此类参数。（存在一个便利函数ensure_future()，用于将协程或Future的参数转换为Future。）

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

为了在协程代码和其他异步框架之间实现互操作性，调度器定义了一个行为类似于Future的Task类。在事件循环级别互操作的框架可以通过向Future添加回调来等待Future完成。同样，调度器提供了一个操作，用于暂停协程直到回调被调用。

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

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

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

传输和协议

对于不熟悉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定义，它为主线程使用一个特殊的子类），并且仅当在调用set_event_loop()之前调用get_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怪癖。

指定时间

与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上（或支持类似“overlapped I/O”API的其他平台上）定义。构造函数接受一个可选参数，一个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()。
• 互联网名称查找：getaddrinfo()、getnameinfo()。
• 互联网连接：create_connection()、create_server()、create_datagram_endpoint()。
• 封装的套接字方法：sock_recv()、sock_sendall()、sock_connect()、sock_accept()。
• 任务和Future支持：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):
    ...

context可能包含许多不同的键，但其中几个被广泛使用

• 'message'：错误消息。
• 'exception'：异常实例；如果没有异常，则为None。
• 'source_traceback'：表示错误中涉及的对象创建时堆栈的字符串列表。
• 'handle_traceback'：表示错误中涉及的句柄创建时堆栈的字符串列表。

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

• get_exception_handler()返回为该循环注册的当前异常处理程序。
• set_exception_handler(handler)设置异常处理程序。
• default_exception_handler(context)此循环实现的*默认*异常处理程序。
• call_exception_handler(context)将*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。Handle是不透明的，只有一个公共方法

• cancel()：取消回调。

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

服务器

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

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

Futures

这里的asyncio.Future类在设计上与PEP 3148中指定的concurrent.futures.Future类相似，但存在细微差异。除非明确提及concurrent.futures.Future，否则本PEP中提及的Future或futures都应理解为指asyncio.Future。支持的公共API如下，并指出了与PEP 3148的差异：

• cancel()。如果Future已经完成（或已取消），则不执行任何操作并返回False。否则，它会尝试取消Future并返回True。如果取消尝试成功，最终Future的状态将变为已取消（因此cancelled()将返回True），并且回调将被调度。对于普通Future，取消总是立即成功；但对于任务（见下文），任务可能会忽略或延迟取消尝试。
• 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在创建时与事件循环关联。

concurrent.futures包中的wait()和as_completed()函数不接受asyncio.Future对象。但是，有类似的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，例如通过向后者添加一个与yield from一起使用的__iter__()方法。为了防止通过调用尚未完成的Future上的result()等意外阻塞事件循环，阻塞操作可能会检测当前线程中是否存在活动的事件循环并引发异常。然而，当前的PEP致力于不依赖Python 3.3之外的任何内容，因此暂时不考虑对concurrent.futures.Future进行更改。

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

• 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 – 暂停协程直到Future完成，然后返回Future的结果，或引发异常，该异常将被传播。（如果Future被取消，它将引发CancelledError异常。）请注意，任务是Future，关于Future的一切也适用于任务。
• result = yield from coroutine – 等待另一个协程产生结果（或引发异常，该异常将被传播）。coroutine表达式必须是对另一个协程的*调用*。
• return expression – 使用yield from向等待此协程的协程产生结果。
• raise exception – 使用yield from在等待此协程的协程中引发异常。

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

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

等待多个协程

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

• asyncio.wait(fs, timeout=None, return_when=ALL_COMPLETED)。这是一个协程，它等待fs给定的Future或协程完成。协程参数将被包装在任务中（见下文）。它返回一个Future，成功时其结果是两个Future集合的元组，(done, pending)，其中done是已完成（或已取消）的原始Future（或包装的协程）的集合，pending是其余的，即仍未完成（或未取消）的Future。请注意，在timeout和return_when的默认情况下，done将始终为空列表。可选参数timeout和return_when具有与concurrent.futures.wait()相同的含义和默认值：timeout，如果不为None，则指定整个操作的超时；return_when指定何时停止。常量FIRST_COMPLETED、FIRST_EXCEPTION、ALL_COMPLETED的定义值和含义与PEP 3148中相同。
  • ALL_COMPLETED（默认）：等待所有Future完成（或直到超时发生）。
  • FIRST_COMPLETED：等待至少一个Future完成（或直到超时发生）。
  • FIRST_EXCEPTION：等待至少一个Future完成但未因设置异常而取消。（将已取消的Future从条件中排除令人惊讶，但PEP 3148就是这样做的。）
• asyncio.as_completed(fs, timeout=None)。返回一个迭代器，其值为Future或协程；等待连续的值会等待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，它会等待所有参数（Future或协程）完成，并返回它们相应结果的列表。如果一个或多个参数被取消或引发异常，则返回的Future将被取消或其异常被设置（与第一个参数发生的情况匹配），并且其余参数将继续在后台运行。取消返回的Future不会影响参数。请注意，协程参数会使用asyncio.async()转换为Future。
• 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)在给定的时间延迟后返回。

任务

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

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

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

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

您可能会问，为什么不自动将所有协程转换为任务？@asyncio.coroutine装饰器可以做到这一点。但是，在一个协程调用另一个协程（依此类推）的情况下，这将大大降低速度，因为切换到“裸”协程的开销比切换到任务要小得多。

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个字节。如果省略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 之外，所有这些类都可以结合 yield from 使用 with 语句来获取锁，并确保无论 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。（但不要替换该对象。）

UNIX上的SIGCHLD处理

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

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

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