KBEngine 内置 Python 3.7 asyncio 事件循环完全指南:获取、调度、网络 I/O 与底层原理
KBEngine 内置 Python 3.7 asyncio 事件循环完全指南:获取、调度、网络 I/O 与底层原理
导读:本文以 KBEngine 仓库内置 Python 3.7.3 所附带的官方文档 asyncio-eventloop.rst 为骨架,系统讲解 asyncio 事件循环(Event Loop)的获取方式、运行与停止、回调调度、网络服务搭建、文件描述符监听、子进程与信号处理等全部低层 API。读完本文,你将掌握事件循环的完整生命周期管理、回调与定时任务调度、基于 transport/protocol 的 TCP/UDP 服务器与客户端编写,以及如何用事件循环 API 集成第三方框架。文中所有概念均可在 asyncio 实现源码 与 test_asyncio 测试套件 中找到对应佐证。
事件循环(Event Loop)是每一个 asyncio 应用的核心。它负责运行异步任务(task)与回调(callback)、执行网络 I/O 操作,以及运行子进程。对于应用开发者而言,通常应使用 asyncio.run() 这类高层 API,很少需要直接引用事件循环对象;本文档主要面向需要细粒度控制事件循环行为的低层代码、库与框架作者——而这恰恰与 KBEngine 这类以 C++ 为主体、内置 Python 脚本环境的服务器引擎高度契合:引擎自身实现了 epoll/select 事件轮询器 驱动的网络框架,其内置 Python 3.7 的 asyncio 事件循环则服务于脚本层的异步编程需求。
获取事件循环
Python 3.7 提供了四个低层函数用于获取、设置或创建事件循环。注意,get_event_loop()、set_event_loop() 与 new_event_loop() 的行为都可以通过 设置自定义事件循环策略(Event Loop Policy) 来改变。
| 函数 | 作用 | 注意事项 |
|---|---|---|
asyncio.get_running_loop() |
返回当前 OS 线程中正在运行的事件循环 | 若没有运行中的事件循环则抛出 RuntimeError;只能在协程或回调中调用(3.7 新增) |
asyncio.get_event_loop() |
获取当前事件循环;若当前线程未设置且未调用过 set_event_loop(),则自动创建一个新事件循环并设为当前事件循环 |
行为较复杂(尤其是使用自定义策略时),在协程与回调中优先使用 get_running_loop();也可考虑直接用 asyncio.run() 替代手工创建/关闭循环 |
asyncio.set_event_loop(loop) |
将 loop 设置为当前 OS 线程的事件循环 |
—— |
asyncio.new_event_loop() |
创建一个新的事件循环对象 | 创建后需手动 set_event_loop() 才会成为当前线程的循环 |
从源码结构看,get_running_loop() 在 events.py 中通过 thread-local 的 _running_loop 记录运行中的循环;而 get_event_loop() 则依赖事件循环策略对象(EventLoopPolicy)的 get_event_loop() 方法,策略可在首次调用时自动创建默认循环。
运行与停止事件循环
事件循环的生命周期由以下方法控制,它们是 BaseEventLoop 在 base_events.py 中的核心实现:
loop.run_until_complete(future):运行直到future(一个Future实例)完成。如果参数是协程对象,则会被隐式调度为asyncio.Task运行。返回 Future 的结果或抛出其异常。loop.run_forever():运行事件循环直到调用stop()。其停止语义分两种情况:- 若在
run_forever()被调用之前就调用了stop(),循环会以超时为零的方式轮询一次 I/O selector,运行所有因 I/O 事件而调度的回调(以及已经调度的回调),然后退出; - 若在
run_forever()运行期间调用stop(),循环会运行完当前这一批回调后退出;注意由回调新调度的回调不会在这一轮运行,而是要等到下次调用run_forever()或run_until_complete()时才会执行。
- 若在
loop.stop():停止事件循环。loop.is_running():返回True表示事件循环正在运行。loop.is_closed():返回True表示事件循环已关闭。loop.close():关闭事件循环。调用时循环必须未在运行;任何挂起的回调都会被丢弃。该方法会清空所有队列并关闭 executor,但不会等待 executor 完成。该方法是幂等且不可逆的——关闭之后不应再调用任何其他方法。await loop.shutdown_asyncgens():安排所有当前打开(open)的异步生成器对象通过aclose()关闭。调用后,若再迭代新的异步生成器,事件循环会发出警告。使用asyncio.run()时无需手动调用此函数(3.6 新增)。
典型的低层关闭流程如下(文档原例):
try:
loop.run_forever()
finally:
loop.run_until_complete(loop.shutdown_asyncgens())
loop.close()
调度回调
立即调度:call_soon / call_soon_threadsafe
loop.call_soon(callback, *args, context=None):调度callback在事件循环的下一轮迭代中以args参数被调用。回调按注册顺序依次调用,每个回调恰好被调用一次。可选的仅关键字参数context允许为回调指定自定义的contextvars.Context,未提供时使用当前上下文(3.7 新增,见 PEP 567)。返回asyncio.Handle实例,可用于之后取消该回调。此方法非线程安全。loop.call_soon_threadsafe(callback, *args, context=None):call_soon()的线程安全版本,必须用于从其他线程调度回调。
关键字参数注意:大多数 asyncio 调度函数不允许直接传关键字参数,应使用 functools.partial:
# 将调度 "print("Hello", flush=True)"
loop.call_soon(
functools.partial(print, "Hello", flush=True))
使用 partial 对象通常比 lambda 更便利,因为 asyncio 在调试与错误信息中能更好地渲染 partial 对象。
延迟调度:call_later / call_at
事件循环提供在未来的某个时刻调用回调的机制,并使用单调时钟(monotonic clock) 来跟踪时间:
loop.call_later(delay, callback, *args, context=None):调度callback在delay秒后调用(delay可为 int 或 float)。返回asyncio.TimerHandle可用于取消。回调恰好调用一次;若两个回调被调度在同一时刻,它们的调用顺序未定义。3.7.1 起修复了此前delay不能超过一天的限制。loop.call_at(when, callback, *args, context=None):在绝对时间戳when(int 或 float,与loop.time()同一时间基准)调用callback,行为与call_later()相同。3.7.1 起修复了when与当前时间之差不能超过一天的限制。loop.time():按事件循环内部单调时钟返回当前时间(float)。
注意:超时时间(相对
delay或绝对when)不应超过一天。定时调度的底层由TimerHandle维护,配合 timer.cpp 这类引擎级定时器可以相互对照理解"单调时钟 + 定时回调"的设计思路。
创建 Future 与 Task
loop.create_future():创建绑定到该事件循环的asyncio.Future对象。这是创建 Future 的首选方式,可让第三方事件循环提供替代的 Future 实现(性能更好或带插桩)(3.5.2 新增)。loop.create_task(coro):调度执行一个协程,返回Task对象。第三方事件循环可使用自己的Task子类实现互操作,此时返回类型是Task的子类。loop.set_task_factory(factory):设置create_task()使用的任务工厂。若factory为None则恢复默认任务工厂;否则factory必须是签名匹配(loop, coro)的可调用对象,其中loop是当前事件循环引用,coro是协程对象,返回值必须是asyncio.Future兼容对象。loop.get_task_factory():返回任务工厂;若在使用默认工厂则返回None。
打开网络连接
创建流式连接:create_connection
await loop.create_connection(protocol_factory, host=None, port=None, *, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None, ssl_handshake_timeout=None)
向 host 与 port 指定的地址建立流式(TCP)传输连接。socket 族根据 host(或 family 参数)可为 socket.AF_INET 或 socket.AF_INET6,socket 类型固定为 socket.SOCK_STREAM。protocol_factory 必须是返回 asyncio 协议实现的可调用对象。该方法在后台尝试建立连接,成功后返回 (transport, protocol) 二元组。
底层操作时序如下:
- 连接建立成功,为其创建 transport;
- 无参调用
protocol_factory,期望返回协议实例; - 调用协议的
connection_made方法将协议实例与 transport 耦合; - 成功时返回
(transport, protocol)元组。
参数要点:
ssl:给定且非假值时创建 SSL/TLS transport(默认创建明文 TCP transport)。若为ssl.SSLContext对象则用该上下文创建 transport;若为True则使用ssl.create_default_context()返回的默认上下文。server_hostname:设置或覆盖目标服务器证书所要匹配的主机名,仅在ssl非None时传入。默认使用host参数值;若host为空则无默认值、必须显式传server_hostname。若server_hostname为空字符串则禁用主机名匹配(存在中间人攻击风险)。family、proto、flags:透传给getaddrinfo()做主机解析的可选地址族、协议与标志,应为socket模块对应常量。sock:若给定,应为已连接好的现有socket.socket对象;此时不得再指定host、port、family、proto、flags与local_addr。local_addr:(local_host, local_port)元组,用于本地绑定 socket。ssl_handshake_timeout:(TLS 连接)等待 TLS 握手完成的秒数,超时则中止连接,None(默认)为60.0秒(3.7 新增)。- 自 3.6 起所有 TCP 连接默认设置
socket.TCP_NODELAY;自 3.5 起ProactorEventLoop支持 SSL/TLS。
高层替代:asyncio.open_connection() 返回可直接用于 async/await 代码的 (StreamReader, StreamWriter) 对。
创建数据报端点:create_datagram_endpoint
await loop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, *, family=0, proto=0, flags=0, reuse_address=None, reuse_port=None, allow_broadcast=None, sock=None)
创建 UDP 数据报连接。socket 族可为 AF_INET、AF_INET6 或 AF_UNIX,类型为 SOCK_DGRAM。成功时返回 (transport, protocol)。
参数要点:
local_addr/remote_addr:(host, port)元组,分别用于本地绑定与连接远端地址,均通过getaddrinfo()解析。family、proto、flags:透传给getaddrinfo(),应为socket模块对应常量。reuse_address:告知内核复用处于TIME_WAIT状态的本地 socket;Unix 上未指定时自动设为True。reuse_port:允许该端点与其他同样设置此标志的端点绑定同一端口。Windows 及部分 Unix 不支持;若socket.SO_REUSEPORT常量未定义则此能力不可用。allow_broadcast:允许向广播地址发送消息。sock:使用预先存在、已连接的 socket 对象;指定时local_addr与remote_addr必须省略(为None)。- 在 Windows 上使用
ProactorEventLoop时不支持此方法。
创建 Unix 连接:create_unix_connection
await loop.create_unix_connection(protocol_factory, path=None, *, ssl=None, sock=None, server_hostname=None, ssl_handshake_timeout=None)
创建 Unix 域连接(AF_UNIX + SOCK_STREAM)。path 为 Unix 域 socket 名称,除指定 sock 外必须提供;支持抽象 Unix socket、str、bytes 与 pathlib.Path 路径(3.7 起 path 可为 path-like 对象)。其余参数含义同 create_connection()。仅 Unix 可用。
创建网络服务器
create_server
await loop.create_server(protocol_factory, host=None, port=None, *, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None, reuse_port=None, ssl_handshake_timeout=None, start_serving=True)
创建监听 host 地址 port 端口的 TCP 服务器(SOCK_STREAM),返回 Server 对象。
参数要点:
protocol_factory:返回协议实现的可调用对象。host:决定监听位置——字符串时绑定单个网络接口;字符串序列时绑定序列中所有接口;空字符串或None时假设所有接口并返回多个 socket(通常一个 IPv4、一个 IPv6)。family:socket.AF_INET或socket.AF_INET6强制 IPv4/IPv6;未设置时由主机名决定(默认AF_UNSPEC)。flags:getaddrinfo()的位掩码。sock:预先存在的 socket 对象;指定时不得再指定host与port。backlog:传给socket.listen()的最大排队连接数(默认 100)。ssl:ssl.SSLContext实例,用于对接受的连接启用 TLS。reuse_address:Unix 上未指定时自动设为True。reuse_port:Windows 不支持。ssl_handshake_timeout:TLS 服务器等待握手完成的秒数,None默认60.0秒(3.7 新增)。start_serving:默认True立即开始接受连接;设为False时需await Server.start_serving()或Server.serve_forever()才能开始接受连接(3.7 新增)。- 3.6 起所有 TCP 连接默认设置
TCP_NODELAY;3.5 起ProactorEventLoop支持 SSL/TLS;3.5.1 起host可为字符串序列。
高层替代:asyncio.start_server() 返回 (StreamReader, StreamWriter) 对。
create_unix_server
await loop.create_unix_server(protocol_factory, path=None, *, sock=None, backlog=100, ssl=None, ssl_handshake_timeout=None, start_serving=True)
与 create_server() 类似,但使用 AF_UNIX socket 族。path 为 Unix 域 socket 名称(除非提供 sock),支持抽象 socket、str、bytes、Path。仅 Unix 可用。
connect_accepted_socket
await loop.connect_accepted_socket(protocol_factory, sock, *, ssl=None, ssl_handshake_timeout=None)
将已接受的连接包装成 transport/protocol 对。供在 asyncio 之外接受连接、但用 asyncio 处理连接的服务器使用。sock 是 socket.accept() 返回的现有 socket 对象;ssl 可设置 SSLContext;ssl_handshake_timeout 默认 60.0 秒。返回 (transport, protocol)(3.5.3 新增)。
传输文件与 TLS 升级
await loop.sendfile(transport, file, offset=0, count=None, *, fallback=True):通过 transport 发送文件,返回发送的总字节数。方法在可用时使用高性能的os.sendfile。file必须是二进制模式打开的普通文件对象;offset指定读取起始位置,count为要传输的总字节数(否则发送到 EOF);即使方法抛出异常,文件位置也始终被更新,可用file.tell()获取实际发送字节数。fallback=True时,在平台不支持 sendfile 系统调用(如 Windows 或 Unix 上的 SSL socket)的情况下,asyncio 会手动读取并发送文件;fallback=False且系统不支持sendfile时抛出SendfileNotAvailableError(3.7 新增)。await loop.start_tls(transport, protocol, sslcontext, *, server_side=False, server_hostname=None, ssl_handshake_timeout=None):将现有基于 transport 的连接升级为 TLS。返回新的 transport 实例,await之后协议必须立即开始使用新实例,传入的旧 transport 实例绝不应再使用。transport与protocol是create_server()/create_connection()之类方法返回的实例;sslcontext是配置好的ssl.SSLContext;server_side=True表示升级服务器侧连接;server_hostname设置/覆盖证书匹配的主机名;ssl_handshake_timeout默认60.0秒(3.7 新增)。
监听文件描述符
以下方法将普通文件描述符接入事件循环(与 KBEngine 引擎层 network 中 event_poller 监听 socket 可读/可写事件的设计思路一致):
loop.add_reader(fd, callback, *args):开始监控fd的可读性,一旦fd可读即以指定参数调用callback。loop.remove_reader(fd):停止监控fd的可读性。loop.add_writer(fd, callback, *args):开始监控fd的可写性,一旦可写即调用callback(传关键字参数请用functools.partial)。loop.remove_writer(fd):停止监控fd的可写性。
这些方法的部分平台限制见 asyncio 平台支持文档。
直接操作 socket 对象
一般而言,使用 create_connection() / create_server() 这类基于 transport 的 API 比直接操作 socket 的实现更快;但当性能不关键、直接操作 socket.socket 更便捷时,可使用以下方法(所有 sock 参数都要求非阻塞 socket):
| 方法 | 说明 |
|---|---|
await loop.sock_recv(sock, nbytes) |
socket.recv() 的异步版,返回 bytes 数据 |
await loop.sock_recv_into(sock, buf) |
将数据接收进 buf 缓冲区,返回写入缓冲区的字节数(3.7 新增) |
await loop.sock_sendall(sock, data) |
socket.sendall() 的异步版,持续发送直到全部发出或出错;成功返回 None |
await loop.sock_connect(sock, address) |
socket.connect() 的异步版;3.5.2 起 address 无需预先解析——先尝试 socket.inet_pton 判断是否已解析,否则用 loop.getaddrinfo 解析 |
await loop.sock_accept(sock) |
socket.accept() 的异步版;socket 须已绑定并监听,返回 (conn, address) 对 |
await loop.sock_sendfile(sock, file, offset=0, count=None, *, fallback=True) |
socket.sendfile() 的异步版,可用时使用高性能 os.sendfile(3.7 新增) |
版本提示:
sock_recv、sock_sendall、sock_accept在 Python 3.7 之前实际返回Future,自 3.7 起均为async def协程方法。
DNS 解析
await loop.getaddrinfo(host, port, *, family=0, type=0, proto=0, flags=0):socket.getaddrinfo的异步版本。await loop.getnameinfo(sockaddr, flags=0):socket.getnameinfo的异步版本。
3.7 起两者均为真正的协程(此前实际返回 Future 对象)。
操作管道与子进程
连接管道
await loop.connect_read_pipe(protocol_factory, pipe):将pipe的读端注册到事件循环,返回(transport, protocol),其中 transport 支持ReadTransport接口。SelectorEventLoop下pipe会被设为非阻塞模式。await loop.connect_write_pipe(protocol_factory, pipe):将pipe的写端注册到事件循环,返回(transport, protocol),其中 transport 支持WriteTransport接口。
注意:
SelectorEventLoop在 Windows 上不支持以上方法,应改用ProactorEventLoop。
运行子进程
以下方法为低层 API;常规 async/await 代码中建议使用高层便捷函数 asyncio.create_subprocess_shell 与 asyncio.create_subprocess_exec。Windows 上默认事件循环不支持子进程,详见 Windows 子进程支持。
await loop.subprocess_exec(protocol_factory, *args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs):由一个或多个字符串参数创建子进程。args必须是str或(按文件系统编码编码的)bytes字符串组成的列表,第一个字符串指定可执行程序,其余为参数,共同构成程序argv。这类似于以shell=False与字符串列表作为首参调用标准库subprocess.Popen,区别是subprocess_exec接收多个字符串参数而非单个列表。protocol_factory必须返回asyncio.SubprocessProtocol的子类。stdin:连接到子进程标准输入的文件类对象,或subprocess.PIPE(默认,创建新管道并连接);stdout:连接标准输出的文件类对象,或subprocess.PIPE(默认);stderr:连接标准错误的文件类对象、subprocess.PIPE(默认)或subprocess.STDOUT(将标准错误连接到与标准输出相同的管道);- 其余关键字参数原样透传给
subprocess.Popen(但bufsize、universal_newlines、shell不得指定)。 - 返回
(transport, protocol),transport 符合asyncio.SubprocessTransport基类。
await loop.subprocess_shell(protocol_factory, cmd, *, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, **kwargs):使用平台 shell 语法从cmd(str或按文件系统编码的bytes)创建子进程,类似于以shell=True调用subprocess.Popen。其余参数见subprocess_exec。
安全提示:应用程序有责任正确引用所有空白与特殊字符,避免 shell 注入漏洞;可用
shlex.quote()对用于构造 shell 命令的字符串做正确转义。
Unix 信号处理
loop.add_signal_handler(signum, callback, *args):将callback设为signum信号的处理函数。回调会与事件循环的其他排队回调及可运行协程一起被调用;与signal.signal注册的信号处理器不同,用此函数注册的回调允许与事件循环交互。信号编号无效或不可捕获时抛ValueError,设置处理器失败时抛RuntimeError。与signal.signal一样,必须在主线程中调用(传关键字参数请用functools.partial)。loop.remove_signal_handler(sig):移除sig信号的处理函数,返回True(已移除)或False(该信号未设置处理器)。仅 Unix 可用。
在线程/进程池中执行代码
await loop.run_in_executor(executor, func, *args):安排 func 在指定 executor 中调用。executor 应为 concurrent.futures.Executor 实例;为 None 时使用默认 executor。返回 asyncio.Future 对象。3.5.3 起 run_in_executor 不再配置其创建的线程池的 max_workers,交由 ThreadPoolExecutor 自行设置默认值。
文档原例完整演示了三种用法——默认线程池、自定义线程池与自定义进程池:
import asyncio
import concurrent.futures
def blocking_io():
# 文件操作(如日志)会阻塞事件循环:放到线程池中运行
with open('/dev/urandom', 'rb') as f:
return f.read(100)
def cpu_bound():
# CPU 密集操作会阻塞事件循环:通常更适合放入进程池
return sum(i * i for i in range(10 ** 7))
async def main():
loop = asyncio.get_running_loop()
## 三种方案:
# 1. 在默认事件循环 executor 中运行:
result = await loop.run_in_executor(
None, blocking_io)
print('default thread pool', result)
# 2. 在自定义线程池中运行:
with concurrent.futures.ThreadPoolExecutor() as pool:
result = await loop.run_in_executor(
pool, blocking_io)
print('custom thread pool', result)
# 3. 在自定义进程池中运行:
with concurrent.futures.ProcessPoolExecutor() as pool:
result = await loop.run_in_executor(
pool, cpu_bound)
print('custom process pool', result)
asyncio.run(main())
loop.set_default_executor(executor):设置run_in_executor使用的默认 executor,应为ThreadPoolExecutor实例(3.7 起传入非ThreadPoolExecutor实例被弃用,将在 3.9 报错)。
异常处理 API
事件循环允许自定义异常处理方式:
loop.set_exception_handler(handler):设置新的事件循环异常处理器。handler为None时恢复默认处理器;否则必须是签名匹配(loop, context)的可调用对象,其中loop是当前事件循环引用,context是包含异常细节的dict。loop.get_exception_handler():返回当前异常处理器;未设置自定义处理器时返回None(3.5.2 新增)。loop.default_exception_handler(context):默认异常处理器。发生异常且未设置处理器时调用;自定义处理器也可调用它来委托默认行为。loop.call_exception_handler(context):调用当前事件循环异常处理器。context是dict,可能包含以下键(未来 Python 版本可能新增键):'message':错误消息;'exception'(可选):异常对象;'future'(可选):asyncio.Future实例;'handle'(可选):asyncio.Handle实例;'protocol'(可选):协议实例;'transport'(可选):transport 实例;'socket'(可选):socket.socket实例。
注意:在子类化的事件循环中不应重载
call_exception_handler();自定义异常处理请使用set_exception_handler()。
启用调试模式
loop.get_debug():获取事件循环的调试模式(bool)。默认值:环境变量PYTHONASYNCIODEBUG设置为非空字符串时为True,否则为False。loop.set_debug(enabled: bool):设置事件循环调试模式。3.7 起新增的-X dev命令行选项也可用于启用调试模式。
更多细节见 asyncio 调试模式文档。
回调句柄(Callback Handles)
调度方法(如 call_soon、call_later)返回的句柄对象:
class asyncio.Handle:由loop.call_soon()与loop.call_soon_threadsafe()返回的回调包装对象。cancel():取消回调;若回调已被取消或已执行则无效果。cancelled():返回True表示回调已被取消(3.7 新增)。
class asyncio.TimerHandle:由loop.call_later()与loop.call_at()返回的回调包装对象,是Handle的子类。when():以float秒返回计划调用时间,为绝对时间戳,与loop.time()使用同一时间基准(3.7 新增)。
服务器对象(Server Objects)
Server 对象由 loop.create_server()、loop.create_unix_server()、start_server() 与 start_unix_server() 创建,不要直接实例化该类。
Server 是异步上下文管理器:在 async with 语句中使用时,保证语句结束时 Server 已关闭且不再接受新连接:
srv = await loop.create_server(...)
async with srv:
# 一些代码
# 此时 srv 已关闭,不再接受新连接。
(3.7 起 Server 是异步上下文管理器。)
常用方法:
close():停止服务:关闭监听 socket,并将sockets属性置为None。已有客户端连接的 socket 保持打开。服务器是异步关闭的,需用wait_closed()协程等待关闭完成。get_loop():返回与该服务器对象关联的事件循环(3.7 新增)。await start_serving():开始接受连接。该方法是幂等的,可在服务器已在服务时调用。create_server()/start_server()的start_serving=False参数可创建初始不接受连接的 Server 对象,此时需调用Server.start_serving()或Server.serve_forever()使其开始接受连接(3.7 新增)。await serve_forever():开始接受连接直到协程被取消;serve_forever任务的取消会导致服务器被关闭。服务器已在接受连接时也可调用;每个 Server 对象只允许存在一个serve_forever任务(3.7 新增)。示例:
async def client_connected(reader, writer):
# 使用 reader/writer 流与客户端通信。例如:
await reader.readline()
async def main(host, port):
srv = await asyncio.start_server(
client_connected, host, port)
await srv.serve_forever()
asyncio.run(main('127.0.0.1', 0))
is_serving():返回True表示服务器正在接受新连接(3.7 新增)。await wait_closed():等待close()方法完成。sockets属性:服务器监听的socket.socket对象列表,服务器关闭后为None(3.7 起返回内部列表的副本)。
事件循环实现:SelectorEventLoop 与 ProactorEventLoop
asyncio 附带两种事件循环实现:SelectorEventLoop 与 ProactorEventLoop。默认情况下 asyncio 在所有平台都配置为使用 SelectorEventLoop。两者分别对应 selector_events.py 与 proactor_events.py,并共享 base_events.py 中的 BaseEventLoop 基类。
class asyncio.SelectorEventLoop:基于selectors模块的事件循环,为给定平台选用最高效的 selector。也可手动配置具体的 selector 实现:
import asyncio
import selectors
selector = selectors.SelectSelector()
loop = asyncio.SelectorEventLoop(selector)
asyncio.set_event_loop(loop)
可用性:Unix、Windows。
class asyncio.ProactorEventLoop:Windows 上使用 "I/O Completion Ports"(IOCP)的事件循环。Windows 上使用示例:
import asyncio
import sys
if sys.platform == 'win32':
loop = asyncio.ProactorEventLoop()
asyncio.set_event_loop(loop)
可用性:仅 Windows。
class asyncio.AbstractEventLoop:asyncio 兼容事件循环的抽象基类。上文"事件循环方法"一节列出的所有方法,都是替代实现AbstractEventLoop应当定义的完整接口清单。
完整示例
以下示例有意演示低层事件循环 API(如 run_forever、call_soon)的用法;现代 asyncio 应用很少需要这样编写,建议考虑 asyncio.run() 这类高层函数。
用 call_soon() 实现 Hello World
import asyncio
def hello_world(loop):
"""打印 'Hello World' 并停止事件循环的回调"""
print('Hello World')
loop.stop()
loop = asyncio.get_event_loop()
# 调度对 hello_world() 的调用
loop.call_soon(hello_world, loop)
# 由 loop.stop() 中断的阻塞调用
try:
loop.run_forever()
finally:
loop.close()
用 call_later() 显示当前日期
回调每隔一秒显示当前日期,5 秒后停止事件循环:
import asyncio
import datetime
def display_date(end_time, loop):
print(datetime.datetime.now())
if (loop.time() + 1.0) < end_time:
loop.call_later(1, display_date, end_time, loop)
else:
loop.stop()
loop = asyncio.get_event_loop()
# 调度对 display_date() 的首次调用
end_time = loop.time() + 5.0
loop.call_soon(display_date, end_time, loop)
# 由 loop.stop() 中断的阻塞调用
try:
loop.run_forever()
finally:
loop.close()
监听文件描述符的读事件
等待文件描述符收到数据后关闭事件循环:
import asyncio
from socket import socketpair
# 创建一对已连接的 socket 文件描述符
rsock, wsock = socketpair()
loop = asyncio.get_event_loop()
def reader():
data = rsock.recv(100)
print("Received:", data.decode())
# 完成:注销文件描述符
loop.remove_reader(rsock)
# 停止事件循环
loop.stop()
# 注册文件描述符的读事件
loop.add_reader(rsock, reader)
# 模拟从网络接收数据
loop.call_soon(wsock.send, 'abc'.encode())
try:
# 运行事件循环
loop.run_forever()
finally:
# 完成。关闭 socket 与事件循环
rsock.close()
wsock.close()
loop.close()
为 SIGINT 和 SIGTERM 设置信号处理器
(此示例仅 Unix 可用。)用 loop.add_signal_handler() 注册 SIGINT 与 SIGTERM 的处理器:
import asyncio
import functools
import os
import signal
def ask_exit(signame):
print("got signal %s: exit" % signame)
loop.stop()
async def main():
loop = asyncio.get_running_loop()
for signame in {'SIGINT', 'SIGTERM'}:
loop.add_signal_handler(
getattr(signal, signame),
functools.partial(ask_exit, signame))
await asyncio.sleep(3600)
print("Event loop running for 1 hour, press Ctrl+C to interrupt.")
print(f"pid {os.getpid()}: send SIGINT or SIGTERM to exit.")
asyncio.run(main())
仓库中的配套实现与验证
本文所述内容在 KBEngine 仓库中并非孤立文档,而是与内置 Python 3.7.3 的完整实现与测试一一对应:
- 版本依据:仓库内置 Python 版本由 patchlevel.h 定义为
PY_MAJOR_VERSION 3、PY_MINOR_VERSION 7,即PY_VERSION "3.7.3"。因此本文中标注"3.7 新增/变更"的 API(get_running_loop、context关键字参数、ssl_handshake_timeout、start_serving、sock_recv_into、sock_sendfile、handle.cancelled()、Server.get_loop()等)均可用。 - 实现源码:事件循环的完整实现位于 Lib/asyncio 目录,包括 base_events.py(
BaseEventLoop、定时调度、executor 调度)、selector_events.py(SelectorEventLoop、sock_* 系列方法、TCP/UDP 端点)、proactor_events.py(Windows IOCP 实现)、events.py(策略与get_event_loop等)、runners.py(asyncio.run的"创建循环→运行协程→关闭循环"三步封装)。 - 测试套件:仓库自带完整的 test_asyncio 测试目录,其中 test_base_events.py 覆盖循环运行/停止与回调调度,test_selector_events.py 覆盖 selector 事件循环、连接与服务器创建,test_proactor_events.py 覆盖 Windows IOCP 实现,test_server.py 覆盖 Server 对象生命周期,另有 test_unix_events.py、test_subprocess.py、test_streams.py 等分别验证管道、子进程与流式 API。读者可将本文示例与这些测试相互印证,深入理解每个 API 的实际行为边界。
相关文档导航:本文属于 asyncio 文档体系的一部分,配套文档还包括 asyncio 高层 API 索引、asyncio 低层 API 索引、asyncio 总览、开发与调试、事件循环策略、协议与传输、流(Streams)、子进程 与 平台支持,可按需深入。