KBEngine 内嵌 Python 3.7.3 的 asyncio 低级 API 完全指南:事件循环、传输层、协议与策略
KBEngine 内嵌 Python 3.7.3 的 asyncio 低级 API 完全指南:事件循环、传输层、协议与策略
导读
本篇技术指南以 kbe/src/lib/python/Doc/library/asyncio-llapi-index.rst 为骨架,系统梳理 asyncio 全套低级 API:从事件循环的获取与生命周期管理,到回调调度、任务与 Future、DNS/网络/套接字操作、信号与子进程,再到 Transport(传输层)、Protocol(协议层)与 Event Loop Policy(事件循环策略)。KBEngine 在其 kbe/src/lib/python 目录下内嵌了完整的 Python 3.7.3 发行版(版本定义见 patchlevel.h),asyncio 的标准库、C 扩展 _asyncio 与官方测试(Lib/test/test_asyncio/)随包完整保留。阅读本文后,你将能够精准索引并正确使用 asyncio 低级 API,同时理解其在底层 selector 事件驱动模型中的实现原理。
适用前提:以下所有 API 均以当前仓库内嵌的 Python 3.7.3 为准,部分 API(如
asyncio.get_running_loop())在该版本中已可用,但与后续 Python 版本(3.10+)的废弃策略不同,请以本仓库实际代码为准。
一、获取事件循环:四个顶层函数
asyncio 提供四个获取或设置事件循环的顶层函数,它们是所有低级 API 的入口:
| 函数 | 说明 |
|---|---|
asyncio.get_running_loop() |
首选方式:返回当前正在运行的事件循环;若没有正在运行的循环则抛出 RuntimeError |
asyncio.get_event_loop() |
获取一个事件循环实例(当前线程正在运行的,或经由 policy 创建的默认循环) |
asyncio.set_event_loop(loop) |
通过当前 policy 将指定循环设置为当前循环 |
asyncio.new_event_loop() |
创建一个全新的事件循环对象(不会自动设为当前循环) |
在仓库的 kbe/src/lib/python/Lib/asyncio/events.py 中,get_event_loop() 在 L739、set_event_loop() 在 L755、new_event_loop() 在 L760 均有明确实现,且全部经由 get_event_loop_policy()(L723)委派给当前进程级策略对象:
# 取自 kbe/src/lib/python/Lib/asyncio/events.py(逻辑示意,非逐字)
def get_event_loop():
return get_event_loop_policy().get_event_loop()
def set_event_loop(loop):
get_event_loop_policy().set_event_loop(loop)
def new_event_loop():
return get_event_loop_policy().new_event_loop()
get_running_loop 与 get_event_loop 的差别
get_running_loop()只能在协程内部调用,返回当前真正在执行的循环,是官方文档标为 preferred 的取循环方式(实现见 events.py L681);get_event_loop()在 3.7.3 中行为较宽松:若当前线程没有运行中的循环,它会通过 policy 创建或返回默认循环;正因如此,官方文档刻意用 "Get an event loop instance (current or via the policy)" 描述它。
使用示例
官方文档引用了 asyncio_example_future 示例:在协程内用 get_running_loop() 获取循环以调度操作:
import asyncio
async def main():
loop = asyncio.get_running_loop() # 在协程内部获取正在运行的循环
fut = loop.create_future()
loop.call_soon(fut.set_result, "done")
print(await fut)
asyncio.run(main())
二、事件循环方法:生命周期、调试与回调调度
事件循环的核心方法定义在 kbe/src/lib/python/Lib/asyncio/base_events.py 的 BaseEventLoop(L358),其抽象接口 AbstractEventLoop 位于 events.py L210。官方索引按主题将方法分为七组,全部可在源码中定位:
2.1 Lifecycle(生命周期)
| 方法 | 说明 | 源码位置 |
|---|---|---|
loop.run_until_complete(future) |
运行循环直到传入的 Future/Task/awaitable 完成 | base_events.py L549 |
loop.run_forever() |
永久运行循环,直到调用 stop() |
base_events.py L522 |
loop.stop() |
停止事件循环(在下一次 I/O 轮询后生效) | — |
loop.close() |
关闭事件循环,释放资源 | — |
loop.is_running() |
返回 True 表示循环正在运行 |
— |
loop.is_closed() |
返回 True 表示循环已关闭 |
— |
await loop.shutdown_asyncgens() |
关闭所有异步生成器 | base_events.py L496 |
官方推荐的经典用法是 run_until_complete(协程会先被 ensure_future 包装为 Task):
loop = asyncio.get_event_loop()
try:
loop.run_until_complete(main())
finally:
loop.close()
shutdown_asyncgens() 是 3.7 新增的重要清理手段:应用退出前 await 它,可确保所有异步生成器的 aclose() 被触发,避免资源泄漏。
2.2 Debugging(调试)
| 方法 | 说明 |
|---|---|
loop.set_debug(enabled) |
启用/禁用调试模式(实现见 base_events.py L1796) |
loop.get_debug() |
查询当前调试模式状态(base_events.py L1793) |
调试模式下,asyncio 会记录 call_soon/create_task 的调用栈,并在协程、Future 未等待时给出更详细的告警,是排查"任务被遗忘"问题的利器。
2.3 Scheduling Callbacks(回调调度)
| 方法 | 说明 | 源码位置 |
|---|---|---|
loop.call_soon(callback, *args) |
尽快调用回调(按注册顺序,同一轮事件处理中执行) | base_events.py L678 |
loop.call_soon_threadsafe(callback, *args) |
call_soon 的线程安全变体,可安全地从其他线程调用 |
base_events.py L731 |
loop.call_later(delay, callback, *args) |
在 delay 秒之后 调用回调,返回 TimerHandle |
base_events.py L640 |
loop.call_at(when, callback, *args) |
在 指定绝对时间 调用回调(时间基准为 loop.time()) |
base_events.py L662 |
call_soon_threadsafe 是实现"外部线程向事件循环投递任务"的标准手段——它内部会唤醒事件循环(写入 self-pipe / 使用 wakeup fd),因此可以在工作线程中安全调用:
import asyncio, threading
def worker(loop):
# 在任意工作线程中安全地向事件循环投递回调
loop.call_soon_threadsafe(on_task_done, "result")
async def main():
t = threading.Thread(target=worker, args=(asyncio.get_running_loop(),))
t.start()
# 继续执行其他逻辑...
call_later 的经典示例见官方文档 asyncio_example_call_later:在事件循环中注册一个延迟回调,同时可配合 TimerHandle.cancel() 取消。
2.4 Thread/Process Pool(线程/进程池)
| 方法 | 说明 | 源码位置 |
|---|---|---|
await loop.run_in_executor(executor, func, *args) |
在 concurrent.futures 执行器中运行 CPU 密集或阻塞函数 |
base_events.py L742 |
loop.set_default_executor(executor) |
为 run_in_executor 设置默认执行器 |
base_events.py L754 |
不传 executor 时,asyncio 使用默认的 ThreadPoolExecutor。由于 asyncio 是单线程事件驱动模型,任何阻塞式函数(如 requests 调用、time.sleep、同步文件 I/O)都应放到 executor 中执行,否则会卡住整个事件循环:
result = await loop.run_in_executor(None, blocking_function, arg1, arg2)
2.5 Tasks and Futures(任务与 Future)
| 方法 | 说明 | 源码位置 |
|---|---|---|
loop.create_future() |
创建 Future 对象 |
base_events.py L394 |
loop.create_task(coro) |
将协程调度为 Task |
base_events.py L398 |
loop.set_task_factory(factory) |
设置 create_task 使用的 Task 工厂 |
base_events.py L412 |
loop.get_task_factory() |
获取当前 Task 工厂 | base_events.py L426 |
set_task_factory 是 3.7 引入的高级扩展点:通过自定义 Task 类(例如带超时、带统计的 Task 子类),可以透明地改变 create_task 的产物类型。仓库的 kbe/src/lib/python/Lib/asyncio/tasks.py 中 Task 类即由 _register_task/_unregister_task 维护全局弱引用集合,供调试与告警使用。
2.6 DNS(域名解析)
| 方法 | 说明 | 源码位置 |
|---|---|---|
await loop.getaddrinfo(host, port, *, family=0, type=0, proto=0, flags=0) |
socket.getaddrinfo 的异步版本 |
base_events.py L781 |
await loop.getnameinfo(sockaddr, flags=0) |
socket.getnameinfo 的异步版本 |
base_events.py L791 |
DNS 解析默认在线程池执行器中进行,避免阻塞事件循环;也可通过 loop.set_default_executor 定制其执行环境。
2.7 Error Handling(异常处理)
| 方法 | 说明 | 源码位置 |
|---|---|---|
loop.call_exception_handler(context) |
调用异常处理器 | base_events.py L1610 |
loop.set_exception_handler(handler) |
设置新的异常处理器 | base_events.py L1543 |
loop.get_exception_handler() |
获取当前异常处理器 | base_events.py L1538 |
loop.default_exception_handler(context) |
默认异常处理器实现 | base_events.py L1560 |
回调、Task 或传输层回调中未被捕获的异常都会进入异常处理器,context 字典包含 message、exception、future 等键。自定义处理器可对未捕获异常做统一记录:
def handler(loop, context):
msg = context.get("message", "Unhandled error")
exc = context.get("exception")
print(f"asyncio error: {msg}, exc={exc!r}")
loop.set_exception_handler(handler)
三、网络、套接字、信号与子进程
3.1 Networking and IPC(网络与进程间通信)
以下方法均在 base_events.py 中有实现,unix 系列则在 unix_events.py:
| 方法 | 说明 | 源码位置 |
|---|---|---|
await loop.create_connection(protocol_factory, host, port, ...) |
打开一个 TCP 连接 | base_events.py L863 |
await loop.create_server(protocol_factory, host, port, ...) |
创建 TCP 服务器 | base_events.py L1289 |
await loop.create_unix_connection(protocol_factory, path, ...) |
打开 Unix 域套接字连接 | unix_events.py L206 |
await loop.create_unix_server(protocol_factory, path, ...) |
创建 Unix 域套接字服务器 | unix_events.py L251 |
await loop.connect_accepted_socket(protocol_factory, sock, ...) |
将已接受的 socket 包装为 (transport, protocol) 对 |
base_events.py L1406 |
await loop.create_datagram_endpoint(protocol_factory, local_addr=None, ...) |
打开数据报(UDP)端点 | base_events.py L1143 |
await loop.sendfile(transport, file, offset=0, count=None, ...) |
通过 transport 发送文件 | base_events.py L1021 |
await loop.start_tls(transport, protocol, sslcontext, ...) |
将现有连接升级为 TLS | base_events.py L1097 |
await loop.connect_read_pipe(protocol_factory, pipe) |
将管道读端包装为 (transport, protocol) 对 |
base_events.py L1435 |
await loop.connect_write_pipe(protocol_factory, pipe) |
将管道写端包装为 (transport, protocol) 对 |
base_events.py L1451 |
官方文档使用 loop.create_connection() 实现了 echo-client 与 socket 连接两个示例,核心模式是"协议工厂 + transport/protocol 解耦":
import asyncio
class EchoClientProtocol(asyncio.Protocol):
def connection_made(self, transport):
self.transport = transport
transport.write(b"Hello, world!") # 数据已发送
def data_received(self, data):
print("Received:", data.decode())
self.transport.close()
async def main():
loop = asyncio.get_running_loop()
transport, protocol = await loop.create_connection(
EchoClientProtocol, "127.0.0.1", 8888)
await protocol.wait_closed() # 等待连接关闭
asyncio.run(main())
create_server 同样返回 transport/protocol 结构,且支持 sock、ssl、backlog、reuse_address 等参数;start_tls 则适用于"先明文认证再升级 TLS"的场景。
3.2 Sockets(套接字)
套接字级 API 允许直接操作 socket.socket 对象(非阻塞模式),实现在 selector_events.py 的 BaseSelectorEventLoop(L42):
| 方法 | 说明 | 源码位置 |
|---|---|---|
await loop.sock_recv(sock, n) |
从套接字接收数据 | selector_events.py L341 |
await loop.sock_recv_into(sock, buf) |
接收数据到指定缓冲区 | selector_events.py L375 |
await loop.sock_sendall(sock, data) |
发送全部数据 | selector_events.py L409 |
await loop.sock_connect(sock, address) |
连接套接字 | — |
await loop.sock_accept(sock) |
接受一个套接字连接 | — |
await loop.sock_sendfile(sock, file, ...) |
通过套接字发送文件 | — |
loop.add_reader(fd, callback, *args) |
开始监视文件描述符是否可读 | — |
loop.remove_reader(fd) |
停止监视可读 | — |
loop.add_writer(fd, callback, *args) |
开始监视文件描述符是否可写 | — |
loop.remove_writer(fd) |
停止监视可写 | — |
从 selector_events.py 的 _sock_recv 实现(L354-L369) 可以看到 asyncio 套接字层的核心机制:当一次 recv 无法立即完成时,内部调用 self.add_reader(fd, self._sock_recv, fut, fd, sock, n),把自身注册为 I/O 回调;数据到达后由 selector 唤醒回调并完成 Future。这正是事件循环 + selector 轮询协同工作的缩影。
add_reader/remove_reader 是官方文档 asyncio_example_watch_fd 示例的主题:直接监视自定义文件描述符(如 FIFO、epoll fd),不经过任何协议层:
import asyncio, os
async def watch_fd(loop, fd):
fut = loop.create_future()
loop.add_reader(fd, lambda: fut.set_result(os.read(fd, 1024)))
data = await fut
loop.remove_reader(fd)
return data
注意:
add_reader是非线程安全的,且只适用于基于 selector 的事件循环(Linux/macOS 默认)。Windows 上的ProactorEventLoop不支持这些套接字方法。
3.3 Unix Signals(Unix 信号)
| 方法 | 说明 | 实现位置 |
|---|---|---|
loop.add_signal_handler(signum, callback, *args) |
为信号添加处理器(仅 Unix) | unix_events.py 的 _UnixSelectorEventLoop |
loop.remove_signal_handler(signum) |
移除信号处理器 | — |
add_signal_handler 的实现依赖 signal.set_wakeup_fd 与自管道(self-pipe)机制:信号处理器只向管道写入一个字节,事件循环被唤醒后再真正执行回调——因此回调总在事件循环线程中运行,无需加锁。官方 asyncio_example_unix_signals 示例演示了对 SIGINT/SIGTERM 的优雅处理:
loop.add_signal_handler(signal.SIGINT, lambda: loop.stop())
loop.add_signal_handler(signal.SIGTERM, lambda: loop.stop())
3.4 Subprocesses(子进程)
| 方法 | 说明 | 源码位置 |
|---|---|---|
loop.subprocess_exec(protocol_factory, program, *args, ...) |
启动一个子进程 | base_events.py L1508 |
loop.subprocess_shell(protocol_factory, cmd, ...) |
通过 shell 命令启动子进程 | base_events.py L1480 |
两个方法返回 (transport, protocol),其中 transport 是 SubprocessTransport。官方 asyncio_example_subprocess_proto 示例通过自定义 SubprocessProtocol 接收子进程的 stdout/stderr:
class MySubprocessProtocol(asyncio.SubprocessProtocol):
def pipe_data_received(self, fd, data):
print(f"fd={fd}: {data!r}")
def process_exited(self):
print("subprocess exited")
async def main():
loop = asyncio.get_running_loop()
transport, protocol = await loop.subprocess_exec(
MySubprocessProtocol, "ls", "-l")
await protocol.complete # 等待子进程退出
子进程的创建与管道事件由 kbe/src/lib/python/Lib/asyncio/base_subprocess.py 支撑,其内部同样借助 add_reader/add_writer 监视子进程管道。
四、Transports(传输层)
所有 transport 都实现自 kbe/src/lib/python/Lib/asyncio/transports.py 中的抽象基类。传输层封装了"底层 I/O 通道",协议层只与 transport 交互,因此同一套协议代码可以运行在 TCP、Unix socket、管道、UDP、子进程等多种载体上。
4.1 通用方法(BaseTransport,L9)
| 方法 | 说明 |
|---|---|
transport.close() |
关闭 transport |
transport.is_closing() |
返回 True 表示正在关闭或已关闭 |
transport.get_extra_info(name, default=None) |
获取 transport 附带信息(如 peername、socket、ssl_object) |
transport.set_protocol(protocol) |
设置新的协议对象 |
transport.get_protocol() |
返回当前协议对象 |
get_extra_info 是获取底层细节的通用入口,例如:
peername = transport.get_extra_info("peername")
sock = transport.get_extra_info("socket")
4.2 读传输(ReadTransport,L44)
| 方法 | 说明 |
|---|---|
transport.is_reading() |
返回 True 表示正在接收数据 |
transport.pause_reading() |
暂停接收(配合流控) |
transport.resume_reading() |
恢复接收 |
pause_reading() 与协议的 pause_writing() 回调配合,构成完整的**背压(backpressure)**机制:接收方处理不过来时暂停读取,发送方缓冲区超水位时收到 pause_writing 通知。
4.3 写传输(WriteTransport,L68)
| 方法 | 说明 |
|---|---|
transport.write(data) |
向 transport 写入数据 |
transport.writelines(list_of_data) |
批量写入缓冲区列表 |
transport.can_write_eof() |
返回 True 表示支持发送 EOF |
transport.write_eof() |
刷新缓冲数据后关闭并发送 EOF |
transport.abort() |
立即关闭 transport(不等待缓冲刷新) |
transport.get_write_buffer_size() |
返回写缓冲区水位信息(含高/低水位) |
transport.set_write_buffer_limits(high=None, low=None) |
设置写流控的高/低水位 |
写流控的完整实现在 transports.py 的 _FlowControlMixin(L233):写入后检查缓冲区大小,超过 high 水位调用 _maybe_pause_protocol() 触发协议的 pause_writing();缓冲排空到 low 水位以下再触发 resume_writing()。默认水位在 L287-L306 中由 _set_write_buffer_limits 计算(默认 high=64KB、low=high/2 量级)。
4.4 数据报传输(DatagramTransport,L158)
由 loop.create_datagram_endpoint() 返回:
| 方法 | 说明 |
|---|---|
transport.sendto(data, addr=None) |
向远端发送数据报 |
transport.abort() |
立即关闭 |
4.5 子进程传输(SubprocessTransport,L181)
由 loop.subprocess_exec() / loop.subprocess_shell() 返回:
| 方法 | 说明 |
|---|---|
transport.get_pid() |
返回子进程 PID |
transport.get_pipe_transport(fd) |
返回指定通信管道(stdin/stdout/stderr)对应的 transport |
transport.get_returncode() |
返回子进程退出码 |
transport.kill() |
杀死子进程 |
transport.send_signal(signal) |
向子进程发送信号 |
transport.terminate() |
停止子进程 |
transport.close() |
杀死子进程并关闭所有管道 |
五、Protocols(协议层)
协议类是回调驱动的:你实现协议子类中的回调方法,asyncio 在相应事件发生时调用它们。协议回调全部定义于 kbe/src/lib/python/Lib/asyncio/protocols.py。
5.1 基础回调(BaseProtocol,L9)
所有协议共享的四个回调:
| 回调 | 触发时机 |
|---|---|
connection_made(transport) |
连接建立时 |
connection_lost(exc) |
连接丢失或关闭时 |
pause_writing() |
transport 缓冲区超过高水位时 |
resume_writing() |
transport 缓冲区排空到低水位以下时 |
5.2 流式协议(Protocol,L64)
用于 TCP、Unix socket、管道:
| 回调 | 触发时机 |
|---|---|
data_received(data) |
收到数据时 |
eof_received() |
收到 EOF 时 |
eof_received() 返回 True 表示保持连接只读方向关闭(半关闭),返回 False/None 表示关闭整个 transport。
5.3 缓冲流式协议(BufferedProtocol,L105)
Python 3.7 新增,用于零拷贝接收的高性能场景:
| 回调 | 触发时机 |
|---|---|
get_buffer(sizehint) |
分配新的接收缓冲区 |
buffer_updated(nbytes) |
缓冲区被写入新数据后 |
eof_received() |
收到 EOF 时 |
通过复用缓冲区,BufferedProtocol 可避免每次 data_received 的数据拷贝,适用于大流量网络服务。仓库在 kbe/src/lib/python/Lib/test/test_asyncio/test_buffered_proto.py 中提供了该机制的完整官方测试。
5.4 数据报协议(DatagramProtocol,L160)
| 回调 | 触发时机 |
|---|---|
datagram_received(data, addr) |
收到数据报时 |
error_received(exc) |
之前的发送/接收操作抛出 OSError 时 |
5.5 子进程协议(SubprocessProtocol,L173)
| 回调 | 触发时机 |
|---|---|
pipe_data_received(fd, data) |
子进程向 stdout/stderr 管道写入数据时 |
pipe_connection_lost(fd, exc) |
与子进程通信的某条管道关闭时 |
process_exited() |
子进程退出时 |
六、Event Loop Policies(事件循环策略)
策略(Policy)是改变 asyncio.get_event_loop() 等函数行为的底层机制——它决定了"当前线程该用哪个事件循环、如何创建新循环"。
6.1 访问策略的 API
| API | 说明 | 源码位置 |
|---|---|---|
asyncio.get_event_loop_policy() |
返回当前进程级策略 | events.py L723 |
asyncio.set_event_loop_policy(policy) |
设置新的进程级策略 | events.py L730 |
AbstractEventLoopPolicy |
策略对象的基类 | events.py L576 |
6.2 策略与平台差异
从仓库源码可以看到策略体系与平台的关系:
- Unix 默认:
DefaultEventLoopPolicy(events.py L632 附近的BaseDefaultEventLoopPolicy)创建基于 selector 的SelectorEventLoop,其实现_UnixSelectorEventLoop位于 unix_events.py L44,底层依赖selectors模块(Linux 上优先使用 epoll); - Windows 可选:
ProactorEventLoop(windows_events.py L303)基于 I/O Completion Ports,支持subprocess_exec等能力,但不支持add_reader等套接字监视方法;windows_events.py L832-L837 定义了WindowsSelectorEventLoopPolicy与WindowsProactorEventLoopPolicy,可通过set_event_loop_policy切换。
自定义策略只需继承 AbstractEventLoopPolicy 并覆写 new_event_loop()/get_event_loop() 等,即可让 get_event_loop() 返回自定义行为的事件循环(例如:全局共享单例循环、按线程缓存循环等):
import asyncio
class MyPolicy(asyncio.DefaultEventLoopPolicy):
def new_event_loop(self):
loop = super().new_event_loop()
loop.set_debug(True) # 让所有新循环默认开启调试模式
return loop
asyncio.set_event_loop_policy(MyPolicy())
七、在 KBEngine 仓库中的定位与验证
KBEngine 在 kbe/src/lib/python 目录下内嵌了完整的 Python 3.7.3 发行版,asyncio 全套低级 API 都有对应实现可供索引:
| 模块文件 | 内容 | 对应章节 |
|---|---|---|
| Lib/asyncio/events.py | 事件循环获取函数、AbstractEventLoop、策略体系 |
第一、二、六章 |
| Lib/asyncio/base_events.py | BaseEventLoop:生命周期、调度、任务、网络、子进程、异常处理 |
第二、三章 |
| Lib/asyncio/selector_events.py | selector 驱动的套接字 API 与 TCP/UDP transport | 第三章 |
| Lib/asyncio/transports.py | 全部 transport 抽象类与流控实现 | 第四章 |
| Lib/asyncio/protocols.py | 全部协议回调抽象类 | 第五章 |
| Lib/asyncio/unix_events.py | Unix 信号、Unix socket、_UnixSelectorEventLoop |
第三章 |
| Lib/asyncio/windows_events.py | ProactorEventLoop 与 Windows 策略 |
第六章 |
| Modules/_asynciomodule.c | asyncio 的 C 加速扩展(_asyncio) |
性能支撑 |
| Lib/test/test_asyncio/ | 官方测试套件(test_events.py、test_transports.py、test_selector_events.py、test_buffered_proto.py、test_unix_events.py 等 20+ 个模块) |
行为验证 |
几点值得注意的仓库事实:
- 版本基准:内嵌解释器为 Python 3.7.3(见 kbe/src/lib/python/Include/patchlevel.h 中
PY_MAJOR_VERSION 3、PY_MINOR_VERSION 7、PY_MICRO_VERSION 3),本文所有 API 行为均以该版本为准; - C 加速扩展:
_asyncio模块(Modules/_asynciomodule.c)为Future/Task等提供 C 实现加速,其构建配置见 PCbuild/_asyncio.vcxproj 与 Modules/Setup.dist; - 官方测试即文档:仓库保留了完整的 asyncio 官方测试套件,例如 test_buffered_proto.py 验证
BufferedProtocol的零拷贝缓冲区协议,test_transports.py 验证 transport 的流控与关闭语义——这些测试是理解各 API 确切行为的权威依据。
八、实践建议:如何选择与组合这些 API
结合官方索引与仓库实现,给出几条可直接落地的选型建议:
- 取循环:协程内部一律使用
asyncio.get_running_loop();仅在没有运行循环的入口处使用get_event_loop()+run_until_complete(); - 网络通信:优先使用
create_connection/create_server+Protocol回调,代码结构清晰且背压机制自动生效;需要极致性能且接受复杂度的场景再考虑BufferedProtocol或裸sock_*+add_reader; - 阻塞任务:任何 CPU 密集或阻塞 I/O 都通过
run_in_executor隔离,必要时用set_default_executor统一配置; - 优雅退出:循环结束前
await loop.shutdown_asyncgens(),并用add_signal_handler(Unix)处理SIGINT/SIGTERM; - 排障:开发期用
loop.set_debug(True)暴露未等待的 Task 与协程告警,再结合自定义set_exception_handler统一记录未捕获异常; - 跨平台:若需在 Windows 上使用子进程与管道,可切换到
ProactorEventLoop(通过策略切换),但注意它不支持add_reader等套接字监视方法。
本文所有 API 索引、实现位置与测试依据,均可直接在当前仓库 kbe/src/lib/python 中逐一核对,构成一份"索引—实现—测试"闭环的低级 asyncio 参考资料。