Python asyncio 传输层与协议层完全指南:从 asyncio-transports 到低层事件循环 API
Python asyncio 传输层与协议层完全指南:从 asyncio-transports 到低层事件循环 API
本文深度讲解 CPython 官方文档 asyncio-protocol.rst 的核心主题——asyncio 的 Transports(传输层) 与 Protocols(协议层)。这是
loop.create_connection、loop.create_server、loop.create_datagram_endpoint、loop.subprocess_exec等低层事件循环 API 的回调式编程模型,也是自研 HTTP、RPC 等高性能网络框架时的标准基础设施。读完本文,你将掌握 Transport/Protocol 类体系的每一类接口方法、回调状态机、写缓冲流控语义,并能徒手写出基于协议类的 TCP/UDP/子进程通信程序,同时理解它们在 Lib/asyncio/transports.py、Lib/asyncio/protocols.py、Lib/asyncio/selector_events.py 中真实的底层实现。
1. 为什么需要 Transports 与 Protocols
官方文档开篇便划清了边界:Transports 与 Protocols 只服务低层事件循环 API(low-level event loop APIs),例如 loop.create_connection()。它们采用回调式编程风格(callback-based programming style),可以支撑高性能网络/IPC 协议(如 HTTP)的实现。本质上,这两层抽象应该被库和框架使用,而绝不应出现在高层 asyncio 应用里——普通应用请优先使用基于流的 asyncio.open_connection / asyncio.start_server,或更上层的 asyncio.StreamReader/StreamWriter。
这一页文档同时覆盖 Transports 与 Protocols 两个主题,二者通过以下三种视角被区分:
- 职责视角:transport 关心字节如何(how)被传输;protocol 决定传输哪些字节(which)、以及在何种时机传输。
- 抽象视角:transport 是对 socket(或同类 I/O 端点)的抽象;protocol 则是站在 transport 视角对一个"应用程序"的抽象。
- 接口视角:二者接口合在一起,定义了一套用于网络 I/O 与进程间 I/O 的抽象接口。
关键在于 transport 与 protocol 对象始终是 1:1 对应:protocol 调用 transport 的方法来发送数据,transport 调用 protocol 的方法来把收到的数据交给它。大多数面向连接的 event loop 方法(如 loop.create_connection())接受一个 protocol_factory 参数,用它为一个连接创建 Protocol 对象(该连接由 Transport 对象表示),并通常返回 (transport, protocol) 元组。
transport, protocol = await loop.create_connection(protocol_factory, host, port)
2. Transports 传输层:通信通道的抽象
实现源码:Lib/asyncio/transports.py
Transport 是 asyncio 为抽象各种通信通道而提供的类。transport 对象永远由 asyncio 事件循环实例化,用户不直接 new。asyncio 为 TCP、UDP、SSL、子进程管道(subprocess pipes) 提供了现成实现;transport 上可用的方法取决于其种类。所有 transport 类均非线程安全(详见文档中多线程约束章节)。
2.1 传输层类层次(Transports Hierarchy)
BaseTransport 是一切传输的基类,包含所有传输共有的方法:
BaseTransport:所有 asyncio transport 共有的方法基类。WriteTransport(BaseTransport):只写连接的基础传输。实例由loop.connect_write_pipe()返回,也被loop.subprocess_exec()等子进程方法使用。ReadTransport(BaseTransport):只读连接的基础传输。实例由loop.connect_read_pipe()返回,也被子进程相关方法(如loop.subprocess_exec())使用。Transport(WriteTransport, ReadTransport):双向传输接口,如一条 TCP 连接。用户不直接实例化,而是调用某个工具函数,把 protocol factory 及其它必要信息传给它;由事件循环方法返回/使用,例如loop.create_connection()、loop.create_unix_connection()、loop.create_server()、loop.sendfile()等。DatagramTransport(BaseTransport):数据报(UDP)连接的传输,由loop.create_datagram_endpoint()返回。SubprocessTransport(BaseTransport):父进程与其子 OS 进程之间连接的抽象,由loop.subprocess_shell()与loop.subprocess_exec()返回。
在源码中,这些类只是抽象接口,几乎所有方法在基类里都 raise NotImplementedError,唯一例外是 WriteTransport.writelines()(其默认实现将迭代对象拼接后调用 write()):
def writelines(self, list_of_data):
data = b''.join(list_of_data)
self.write(data)
(见 transports.py)
2.2 BaseTransport:通用方法与 get_extra_info 元信息查询
BaseTransport.close():关闭 transport。若存在出站数据缓冲,缓冲数据会异步冲刷;此后不再接收数据;待缓冲排空后,protocol 的connection_lost()会以None为参数被调用。transport 一旦关闭便不应再使用。BaseTransport.is_closing():transport 正在关闭或已关闭时返回True。BaseTransport.get_extra_info(name, default=None):查询 transport 自身或其底层资源的信息。name是待查信息的字符串;default是在信息不可用、或当前第三方事件循环实现/当前平台不支持查询时返回的值。例如要取到底层 socket 对象:
sock = transport.get_extra_info('socket')
if sock is not None:
print(sock.getsockopt(...))
文档列出了各类型传输上可查询的信息类别,实践中这是拿对端地址、套接字、TLS 参数的首选途径:
| 类别 | 键 name |
含义 |
|---|---|---|
| socket | 'peername' |
远端地址,socket.getpeername() 的结果(出错时为 None) |
'socket' |
socket.socket 实例 |
|
'sockname' |
本端地址,socket.getsockname() 的结果 |
|
| SSL socket | 'compression' |
使用的压缩算法字符串;未压缩连接为 None(ssl.SSLSocket.compression()) |
'cipher' |
三元组:所用 cipher 名称、定义其使用的 SSL 协议版本、使用的密钥位数(ssl.SSLSocket.cipher()) |
|
'peercert' |
对端证书(ssl.SSLSocket.getpeercert()) |
|
'sslcontext' |
ssl.SSLContext 实例 |
|
'ssl_object' |
ssl.SSLObject 或 ssl.SSLSocket 实例 |
|
| pipe | 'pipe' |
管道对象 |
| subprocess | 'subprocess' |
subprocess.Popen 实例 |
实现上,get_extra_info 只是对内部 _extra 字典的一次查询(transports.py);而 _extra 字典由具体实现填充——例如 selector_events.py 中 _SelectorTransport.__init__ 会写入 'socket'、'sockname'、'peername' 等键。
BaseTransport.set_protocol(protocol):设置新 protocol。只有当新旧两个 protocol 都声明支持切换时才应切换(典型的例子是loop.start_tls()升级到 SSL 时)。配套的BaseTransport.get_protocol()返回当前 protocol。
2.3 ReadTransport:只读传输与读取流控
ReadTransport.is_reading()(3.7+):transport 正在接收新数据时返回True。ReadTransport.pause_reading():暂停接收端。在resume_reading()被调用前,不会有数据递交给 protocol 的data_received()。(3.7 起该方法是幂等的:在已暂停或已关闭的 transport 上也可调用。)ReadTransport.resume_reading():恢复接收端。若有可读数据,data_received()会再次被调用。(3.7 起同样是幂等的:已在读取状态也可调用。)
以 Linux/BSD 默认的 selector 事件循环实现为例,这三个方法直接操作 selector 的读写注册表(selector_events.py):
def is_reading(self):
return not self.is_closing() and not self._paused
def pause_reading(self):
if not self.is_reading():
return
self._paused = True
self._loop._remove_reader(self._sock_fd) # 从 epoll/kqueue 摘除读关注
def resume_reading(self):
if self._closing or not self._paused:
return
self._paused = False
self._add_reader(self._sock_fd, self._read_ready) # 重新注册读回调
也就是说"暂停读取"在底层就是从事件循环的 selector 中摘除该 fd 的读事件,从而让内核不再上报可读事件、避免持续占用 CPU。
2.4 WriteTransport:只写传输与写缓冲流控
WriteTransport.abort():立即关闭 transport,不等待未完成操作。缓冲数据会丢失,不再接收数据,connection_lost()最终以None被调用。对应源码中_force_close(exc)会先清空_buffer(selector_events.py)。WriteTransport.can_write_eof():transport 是否支持write_eof()。WriteTransport.get_write_buffer_size():当前出站缓冲区字节数。WriteTransport.get_write_buffer_limits()(3.4.2+):返回(low, high)二元组,即写流控的低/高水位(单位字节),由set_write_buffer_limits()设置。WriteTransport.set_write_buffer_limits(high=None, low=None):见下节详解。WriteTransport.write(data):写入若干字节。不阻塞:数据先入缓冲,再由事件循环异步发送。WriteTransport.writelines(list_of_data):写入一组字节(list 或任意 iterable)。功能等价于逐个元素调用write(),但实现可能更高效——selector 实现会把每个片段打包为 memoryview 统一入队,甚至用sendmsg()一次写入多段(selector_events.py)。WriteTransport.write_eof():冲刷所有缓冲后关闭写端;仍可继续接收数据。若 transport(如 SSL)不支持半关闭连接,该方法可抛NotImplementedError。
写缓冲水位:何时触发 pause_writing/resume_writing
set_write_buffer_limits(high, low) 决定 protocol 的 pause_writing() / resume_writing() 何时被调用:
- 缓冲大小大于等于 high 时……注意精确边界:官方文档强调,
pause_writing()需要缓冲大小严格超过(strictly over)high 水位才触发;反之resume_writing()在缓冲大小等于或低于(equal or lower)low 水位时触发。这些端点条件保证了当任一水位为 0 时行为依然符合预期。 - 若仅指定
high,low默认为实现相关的、≤ high 的值;只给 high 不给 low 时,low不能为负。 - high 置 0 会强制 low 也为 0,结果是只要缓冲非空就立刻
pause_writing();low 置 0 则要等缓冲完全清空才resume_writing()。文档明确提示:把任一水位设为 0 通常并非最优,因为它削弱了"I/O 与计算并行"的机会(高频的暂停/恢复回调会打断应用持续写入与事件循环推进的节奏)。
关于"实现相关默认值",可以在 transports.py 的 _FlowControlMixin._set_write_buffer_limits() 找到默认算法:
def _set_write_buffer_limits(self, high=None, low=None):
if high is None:
if low is None:
high = 64 * 1024 # 默认高水位:64 KiB
else:
high = 4 * low
if low is None:
low = high // 4 # 默认低水位:高水位的 1/4
if not high >= low >= 0:
raise ValueError(
f'high ({high!r}) must be >= low ({low!r}) must be >= 0')
self._high_water = high
self._low_water = low
即:未设置任何参数时,high 默认为 64 KiB、low 默认为 16 KiB;只给 high 时 low 取 high // 4;只给 low 时 high 取 4 * low。配合 _maybe_pause_protocol()/_maybe_resume_protocol()(transports.py)可以看出:每次写入入队使缓冲增大后调用前者判断是否需要 pause_writing(),每次数据被内核取走、缓冲缩水后调用后者判断是否 resume_writing()。这两处回调异常会被统一收集进事件循环的 exception handler,而非直接抛出。
另外值得注意:protocols.py 的 docstring 特别注明,pause_writing()/resume_writing() 是唯一不经 EventLoop.call_soon() 间接调用的 protocol 回调——如果它也走 call_soon() 延迟执行,那么当应用在事件循环让步前持续狂写时,暂停指令将永远来不及生效。这正是它必须在发送路径上同步直调的原因。
2.5 DatagramTransport:UDP 数据报传输
DatagramTransport.sendto(data, addr=None):向addr(transport 相关的目标地址)发送data;addr为None时发给创建 transport 时指定的目标地址。不阻塞,先入缓冲异步发送。- 3.13 起:可以用空 bytes 发送零长度数据报;用于流控的缓冲大小计算也改为把数据报头计入(见 selector_events.py,
self._buffer_size += len(data) + self._header_size,_header_size = 8)。
- 3.13 起:可以用空 bytes 发送零长度数据报;用于流控的缓冲大小计算也改为把数据报头计入(见 selector_events.py,
DatagramTransport.abort():立即关闭,丢弃缓冲数据、不再接收,connection_lost()最终以None回调。
selector 实现里 UDP 还区分了"已连接 UDP"与"未连接 UDP":_SelectorDatagramTransport 会优先尝试立即 send()/sendto(),失败(BlockingIOError)才注册写事件排队重发;每次发送产生 OSError 会转交给 protocol 的 error_received()(selector_events.py)。
2.6 SubprocessTransport:子进程传输
抽象父进程与子 OS 进程之间的连接,实例来自 loop.subprocess_shell() 与 loop.subprocess_exec():
SubprocessTransport.get_pid():以整数返回子进程 PID。SubprocessTransport.get_pipe_transport(fd):取与文件描述符fd对应的管道 transport:0:标准输入(stdin)的可写流式 transport;若子进程未以stdin=PIPE创建则为None;1:标准输出(stdout)的可读流式 transport;未以stdout=PIPE创建则为None;2:标准错误(stderr)的可读流式 transport;未以stderr=PIPE创建则为None;- 其它
fd:一律None。
SubprocessTransport.get_returncode():返回子进程返回码(整数),未返回时为None,语义同subprocess.Popen.returncode。SubprocessTransport.kill():杀死子进程。POSIX 上发SIGKILL;Windows 上等价于terminate()(参考subprocess.Popen.kill)。SubprocessTransport.send_signal(signal):向子进程发送信号编号signal(同Popen.send_signal)。SubprocessTransport.terminate():终止子进程。POSIX 发SIGTERM;Windows 调用 Win32 APITerminateProcess()(同Popen.terminate)。SubprocessTransport.close():若子进程尚未返回则调用kill(),并关闭 stdin/stdout/stderr 管道的 transports。
3. Protocols 协议层:回调接口与状态机
asyncio 提供一组抽象基类用于实现网络协议,它们必须与 transports 搭配使用。抽象基类 protocol 的子类可以实现部分或全部方法;所有方法本质上都是回调(callbacks):由 transport 在特定事件发生时调用(如收到数据时),即"对应的 transport 应该调用基类协议方法"。
3.1 协议基类速览(Base Protocols)
BaseProtocol:所有协议共享方法的基类。Protocol(BaseProtocol):实现流式协议(TCP、Unix socket 等)的基类。BufferedProtocol(BaseProtocol):实现"手动控制接收缓冲"流式协议的基类。DatagramProtocol(BaseProtocol):实现数据报(UDP)协议的基类。SubprocessProtocol(BaseProtocol):实现与子进程通信(单向管道)协议的基类。
在 protocols.py 中这些基类的所有回调默认都是空实现(不抛异常),因此你可以只覆写关心的方法。
3.2 BaseProtocol:连接回调与流控回调
所有 asyncio 协议都可以实现 BaseProtocol 回调。
连接回调(Connection Callbacks)
连接回调在所有协议上都会被调用,且每次成功连接恰好各一次;其它一切 protocol 回调只能在这两个方法之间被调用。
BaseProtocol.connection_made(transport):连接建立时调用。参数transport即代表该连接的 transport;protocol 负责保存这个 transport 引用(例如存为self.transport),否则后续无法发数据。BaseProtocol.connection_lost(exc):连接丢失或被关闭时调用。参数是异常对象或None——后者表示收到正常的 EOF,或本端中止/关闭了连接。
流控回调(Flow Control Callbacks)
transport 用它们暂停/恢复 protocol 的写入。细节见 2.4 节 WriteTransport.set_write_buffer_limits()。
BaseProtocol.pause_writing():transport 缓冲超过高水位时被调用。BaseProtocol.resume_writing():transport 缓冲排空至低水位以下时被调用。
再次强调文档中的精确边界(结合 protocols.py 的 docstring 更清晰):
若缓冲大小等于高水位,
pause_writing()不被调用——必须严格超过;反之当缓冲大小等于或低于低水位时调用resume_writing()。这两个端点条件用于保证任一水位为 0 时行为正确。pause_writing()一旦触发只调用一次(即便后续继续追加数据),直到resume_writing()配对恢复。
3.3 Protocol:流式协议
loop.create_server()、loop.create_unix_server()、loop.create_connection()、loop.create_unix_connection()、loop.connect_accepted_socket()、loop.connect_read_pipe()、loop.connect_write_pipe() 等事件方法都接受返回流式协议的 factory。
Protocol.data_received(data):收到数据时调用。data是非空 bytes 对象。数据是否被缓冲、分块或重组取决于 transport——一般来说不要依赖具体的分块语义,应让解析逻辑通用且灵活,但数据总是按正确顺序到达。连接打开期间此方法可被调用任意多次。Protocol.eof_received():对端表示不再发送数据时调用(例如对端同样用 asyncio 时调用了transport.write_eof())。最多调用一次;一旦eof_received()被调用,data_received()不再被调用。- 返回值语义:返回假值(含
None)→ transport 关闭自己;返回真值 → 是否关闭由协议方决定。默认实现返回None,因此隐式关闭连接。SSL 等不支持半关闭连接的 transport,即便返回真值也会被强制关闭。
- 返回值语义:返回假值(含
Protocol 的完整生命周期状态机(CM=connection_made、DR=data_received、ER=eof_received、CL=connection_lost):
start -> connection_made
[-> data_received]*
[-> eof_received]?
-> connection_lost -> end
3.4 BufferedProtocol:手动接收缓冲(3.7+)
BufferedProtocol 适用于所有支持流式协议的 event loop 方法。 它允许协议实现显式地手动分配和控制接收缓冲。事件循环随后可复用协议提供的缓冲,避免不必要的内存拷贝,这对接收大量数据的协议能带来明显的性能提升;精巧的实现甚至可在创建连接时只分配一次缓冲,显著减少分配次数。
它新增两个回调:
BufferedProtocol.get_buffer(sizehint):被调用来分配新的接收缓冲。sizehint是推荐的最小尺寸——返回比它更小或更大的缓冲都可以;sizehint为-1时尺寸任意;返回零尺寸缓冲是错误。get_buffer()必须返回实现**缓冲协议(buffer protocol)**的对象(如bytearray、memoryview等)。BufferedProtocol.buffer_updated(nbytes):缓冲被写入接收数据后调用;nbytes是写入缓冲的总字节数。BufferedProtocol.eof_received():语义与Protocol.eof_received()相同。
get_buffer() 在连接期间可被调用任意多次;但 eof_received() 至多一次,一旦被调用,get_buffer() 与 buffer_updated() 便不再出现。状态机(GB=get_buffer、BU=buffer_updated):
start -> connection_made
[-> get_buffer
[-> buffer_updated]?
]*
[-> eof_received]?
-> connection_lost -> end
底层零拷贝路径是怎么实现的
在默认 selector 实现中,transport 的读回调会根据 protocol 类型选择不同派发路径(selector_events.py):set_protocol() 时若 protocol 是 BufferedProtocol 子类,_read_ready_cb 指向 _read_ready__get_buffer,否则指向 _read_ready__data_received。两者的差别恰是文档所述"少一次拷贝"的关键:
# 普通 Protocol:先 recv 到内部缓冲,再传给 data_received(data),存在一次拷贝
data = self._sock.recv(self.max_size)
...
self._protocol.data_received(data)
# BufferedProtocol:直接把内核数据 recv_into 到协议自己分配的缓冲里,零拷贝直达
buf = self._protocol.get_buffer(-1) # 向协议要缓冲
nbytes = self._sock.recv_into(buf) # 内核直接写入该缓冲
self._protocol.buffer_updated(nbytes) # 告知写入字节数
这正是 protocols.py 中 _feed_data_to_buffered_proto() 的配套逻辑:当协议返回的缓冲比待投递数据小(如阻塞式管道写、Proactor 回调场景)时,它会循环 get_buffer() -> 切片拷贝 -> buffer_updated(),直到把数据全部喂完,且若 get_buffer() 返回空缓冲会抛 RuntimeError('get_buffer() returned an empty buffer')。测试可参考 Lib/test/test_asyncio/test_buffered_proto.py 中的 ReceiveStuffProto 与 test_buffered_proto_create_connection。
3.5 DatagramProtocol:数据报(UDP)协议
DatagramProtocol 实例应由传给 loop.create_datagram_endpoint() 的 protocol factory 构造。
DatagramProtocol.datagram_received(data, addr):收到一个数据报时调用。data为包含载荷的 bytes 对象;addr为对端地址,确切格式取决于 transport。DatagramProtocol.error_received(exc):当某次先前的发送/接收操作抛出OSError时调用,exc为OSError实例。这只在罕见条件下触发:transport(如 UDP)检测到某个数据报无法送达收件人;多数情况下不可达的数据报会被静默丢弃。
BSD 系系统流控提示:macOS、FreeBSD 等 BSD 系统上,数据报协议不支持流控——因为没有可靠手段检测"因写入过多数据包导致的发送失败"。socket 看起来永远是"就绪"的,多余的数据包会被直接丢弃;
errno为errno.ENOBUFS的OSError可能抛出也可能不抛——若抛出会报告给error_received(),否则被忽略。
3.6 SubprocessProtocol:子进程协议
SubprocessProtocol 实例应由传给 loop.subprocess_exec() 与 loop.subprocess_shell() 的 factory 构造:
SubprocessProtocol.pipe_data_received(fd, data):子进程向其 stdout/stderr 管道写入数据时调用。fd为管道的整数文件描述符,data为收到的非空 bytes 对象。SubprocessProtocol.pipe_connection_lost(fd, exc):与子进程通信的某根管道关闭时调用。fd为被关闭的文件描述符。SubprocessProtocol.process_exited():子进程退出时调用。注意:它可能先于pipe_data_received()/pipe_connection_lost()被调用(即先知道退出、管道数据后到达),编写清理逻辑时必须容忍这种乱序。
4. 深入底层:事件循环如何"接线" Transport 与 Protocol
回顾 Lib/asyncio/base_events.py,create_connection(L1066)、create_server(L1542)、create_datagram_endpoint(L1388)、connect_read_pipe(L1716)、connect_write_pipe(L1732)、subprocess_shell(L1761)、subprocess_exec(L1797)等都由事件循环实现。典型流程(以 TCP 为例):
- 事件循环解析地址、创建并连接 socket;
- 调用传入的
protocol_factory()实例化协议对象; - 事件循环内部实例化对应 transport(如 selector 实现下的
_SelectorSocketTransport),并在构造时保存 protocol 引用、填充_extra信息(socket/sockname/peername); - transport 用
loop.call_soon()调度protocol.connection_made(self),随后注册读事件——如 selector_events.py 注释所言:"only start reading when connection_made() has been called"(确保连接就绪回调先于任何数据到达); - 此后每当内核报告可读,
_read_ready()分派到data_received/get_buffer路径(见 3.4);每当写入缓冲区变空且调用了close(),则触发_call_connection_lost(None)通知协议。
这条"先 connection_made、后注册读写"的顺序保证了协议回调的确定性,也正是文档状态机得以成立的前提。在 Proactor(Windows IOCP)、SSL(见 Lib/asyncio/sslproto.py 中实现 BufferedProtocol 的 SSLProtocol)及 Unix 管道(Lib/asyncio/unix_events.py 的 _UnixReadPipeTransport/_UnixWritePipeTransport)等实现里,同样的接口约定被复用——这就是 Transport/Protocol 抽象真正的价值:业务协议代码与底层 I/O 机制解耦。
5. 完整实战示例:TCP/UDP/子进程协议编程
以下五个示例均直接取自官方文档(asyncio-protocol.rst 的 Examples 章节),运行于 Python 3.7+(asyncio.get_running_loop())。
5.1 TCP Echo Server(loop.create_server)
回显服务端:收到数据原样发回,然后关闭连接。
import asyncio
class EchoServerProtocol(asyncio.Protocol):
def connection_made(self, transport):
peername = transport.get_extra_info('peername')
print('Connection from {}'.format(peername))
self.transport = transport
def data_received(self, data):
message = data.decode()
print('Data received: {!r}'.format(message))
print('Send: {!r}'.format(message))
self.transport.write(data)
print('Close the client socket')
self.transport.close()
async def main():
# Get a reference to the event loop as we plan to use
# low-level APIs.
loop = asyncio.get_running_loop()
server = await loop.create_server(
EchoServerProtocol,
'127.0.0.1', 8888)
async with server:
await server.serve_forever()
asyncio.run(main())
对照:使用高层
asyncio.start_server的流式 TCP 回显服务见文档 asyncio-streams.rst 的 "TCP echo server using streams" 示例。低层示例更短,但需要自己继承Protocol并管理 transport。
5.2 TCP Echo Client(loop.create_connection)
回显客户端:发送数据后等待连接被服务端关闭。
import asyncio
class EchoClientProtocol(asyncio.Protocol):
def __init__(self, message, on_con_lost):
self.message = message
self.on_con_lost = on_con_lost
def connection_made(self, transport):
transport.write(self.message.encode())
print('Data sent: {!r}'.format(self.message))
def data_received(self, data):
print('Data received: {!r}'.format(data.decode()))
def connection_lost(self, exc):
print('The server closed the connection')
self.on_con_lost.set_result(True)
async def main():
# Get a reference to the event loop as we plan to use
# low-level APIs.
loop = asyncio.get_running_loop()
on_con_lost = loop.create_future()
message = 'Hello World!'
transport, protocol = await loop.create_connection(
lambda: EchoClientProtocol(message, on_con_lost),
'127.0.0.1', 8888)
# Wait until the protocol signals that the connection
# is lost and close the transport.
try:
await on_con_lost
finally:
transport.close()
asyncio.run(main())
这里的惯用法值得学习:on_con_lost = loop.create_future() 让回调世界与协程世界对接——connection_lost 回调里 set_result,主协程 await 该 future。跑通 5.1 与 5.2,即可看到典型的一问一答输出。
5.3 UDP Echo Server(loop.create_datagram_endpoint)
UDP 回显服务端:单个协议实例服务所有客户端请求,不区分连接。
import asyncio
class EchoServerProtocol:
def connection_made(self, transport):
self.transport = transport
def datagram_received(self, data, addr):
message = data.decode()
print('Received %r from %s' % (message, addr))
print('Send %r to %s' % (message, addr))
self.transport.sendto(data, addr)
async def main():
print("Starting UDP server")
# Get a reference to the event loop as we plan to use
# low-level APIs.
loop = asyncio.get_running_loop()
# One protocol instance will be created to serve all
# client requests.
transport, protocol = await loop.create_datagram_endpoint(
EchoServerProtocol,
local_addr=('127.0.0.1', 9999))
try:
await asyncio.sleep(3600) # Serve for 1 hour.
finally:
transport.close()
asyncio.run(main())
注意:这个协议类不继承 asyncio.DatagramProtocol 也可以运行——因为基类回调默认是空实现(见第 3.1 节说明),鸭子类型足够。
5.4 UDP Echo Client(loop.create_datagram_endpoint)
UDP 回显客户端:发一条消息,收到应答后关闭 transport。
import asyncio
class EchoClientProtocol:
def __init__(self, message, on_con_lost):
self.message = message
self.on_con_lost = on_con_lost
self.transport = None
def connection_made(self, transport):
self.transport = transport
print('Send:', self.message)
self.transport.sendto(self.message.encode())
def datagram_received(self, data, addr):
print("Received:", data.decode())
print("Close the socket")
self.transport.close()
def error_received(self, exc):
print('Error received:', exc)
def connection_lost(self, exc):
print("Connection closed")
self.on_con_lost.set_result(True)
async def main():
# Get a reference to the event loop as we plan to use
# low-level APIs.
loop = asyncio.get_running_loop()
on_con_lost = loop.create_future()
message = "Hello World!"
transport, protocol = await loop.create_datagram_endpoint(
lambda: EchoClientProtocol(message, on_con_lost),
remote_addr=('127.0.0.1', 9999))
try:
await on_con_lost
finally:
transport.close()
asyncio.run(main())
此处 error_received 展示了 3.5 节的错误回调入口,而 UDP "connected socket"(通过 remote_addr 创建)是 3.13 前流控/异常报告能正常工作的前提之一。
5.5 接入已存在的 socket(loop.create_connection(sock=...))
用协议对象等待一个已经创建好的 socket 收到数据(本例用 socket.socketpair() 造一对连通 socket 模拟网络收发):
import asyncio
import socket
class MyProtocol(asyncio.Protocol):
def __init__(self, on_con_lost):
self.transport = None
self.on_con_lost = on_con_lost
def connection_made(self, transport):
self.transport = transport
def data_received(self, data):
print("Received:", data.decode())
# We are done: close the transport;
# connection_lost() will be called automatically.
self.transport.close()
def connection_lost(self, exc):
# The socket has been closed
self.on_con_lost.set_result(True)
async def main():
# Get a reference to the event loop as we plan to use
# low-level APIs.
loop = asyncio.get_running_loop()
on_con_lost = loop.create_future()
# Create a pair of connected sockets
rsock, wsock = socket.socketpair()
# Register the socket to wait for data.
transport, protocol = await loop.create_connection(
lambda: MyProtocol(on_con_lost), sock=rsock)
# Simulate the reception of data from the network.
loop.call_soon(wsock.send, 'abc'.encode())
try:
await protocol.on_con_lost
finally:
transport.close()
wsock.close()
asyncio.run(main())
对照:用低层
loop.add_reader()直接监听 fd 的示例见官方文档 "watch a file descriptor for read events";用高层 streamsopen_connection注册已打开 socket 的版本见 "register an open socket to wait for data using streams" 一节。可以看到,create_connection(sock=...)是把已有 fd "搬进"事件循环的标准入口。
5.6 loop.subprocess_exec() 与 SubprocessProtocol
用子进程协议获取 date 输出并等待子进程退出:
import asyncio
import sys
class DateProtocol(asyncio.SubprocessProtocol):
def __init__(self, exit_future):
self.exit_future = exit_future
self.output = bytearray()
self.pipe_closed = False
self.exited = False
def pipe_connection_lost(self, fd, exc):
self.pipe_closed = True
self.check_for_exit()
def pipe_data_received(self, fd, data):
self.output.extend(data)
def process_exited(self):
self.exited = True
# process_exited() method can be called before
# pipe_connection_lost() method: wait until both methods are
# called.
self.check_for_exit()
def check_for_exit(self):
if self.pipe_closed and self.exited:
self.exit_future.set_result(True)
async def get_date():
# Get a reference to the event loop as we plan to use
# low-level APIs.
loop = asyncio.get_running_loop()
code = 'import datetime as dt; print(dt.datetime.now())'
exit_future = asyncio.Future(loop=loop)
# Create the subprocess controlled by DateProtocol;
# redirect the standard output into a pipe.
transport, protocol = await loop.subprocess_exec(
lambda: DateProtocol(exit_future),
sys.executable, '-c', code,
stdin=None, stderr=None)
# Wait for the subprocess exit using the process_exited()
# method of the protocol.
await exit_future
# Close the stdout pipe.
transport.close()
# Read the output which was collected by the
# pipe_data_received() method of the protocol.
data = bytes(protocol.output)
return data.decode('ascii').rstrip()
date = asyncio.run(get_date())
print(f"Current date: {date}")
check_for_exit() 中的"双条件汇合"正是 3.6 节强调的回调乱序问题的标准解法:process_exited() 可能先于 pipe_connection_lost(),只有管道已关且进程已退,才认为收尾完成。使用高层 API(asyncio.create_subprocess_exec + StreamReader)的同一示例见官方文档对应章节。
6. 低层协议编程的测试与验证路径
想快速验证上述行为、或自行实现协议类后做回归,可阅读并复用标准库测试套件:
- Lib/test/test_asyncio/test_protocols.py:协议抽象基类的基本契约;
- Lib/test/test_asyncio/test_buffered_proto.py:
BufferedProtocol的get_buffer/buffer_updated与事件循环对接、零拷贝收包路径,含基于socketpair的功能测试; - Lib/test/test_asyncio/test_selector_events.py:selector 实现下读写、EOF、
pause_reading/resume_reading等传输行为; - Lib/test/test_asyncio/test_unix_events.py 与 Lib/test/test_asyncio/test_subprocess.py:管道与子进程 transport/protocol 行为。
7. 选型总结:何时使用低层 Transports/Protocols
| 使用场景 | 推荐 API 层 |
|---|---|
| 普通应用中的客户端/服务端通信 | 高层:asyncio.open_connection / asyncio.start_server(Streams) |
| 框架/库需要精确控制字节流、实现自有协议状态机 | 低层:Protocol/BufferedProtocol + 上述 event loop 方法 |
| 大流量接收、希望消除中间拷贝 | BufferedProtocol(3.7+),单连接预分配缓冲 |
| UDP 通信 | DatagramProtocol + loop.create_datagram_endpoint() |
| 启动子进程并逐字节消费其 stdout/stderr | SubprocessProtocol + loop.subprocess_exec()/subprocess_shell() |
| 把既有 fd/对端已 accept 的 socket 纳入事件循环 | loop.create_connection(sock=...) / loop.connect_accepted_socket() |
| 只读/只写管道端点 | loop.connect_read_pipe() / loop.connect_write_pipe() |
最后回到官方文档最核心的两句忠告,值得反复咀嚼:
- transport 决定字节怎么传,protocol 决定传哪些字节——划分好二者职责,是写出可维护网络框架的前提;
- transport 与 protocol 永远是 1:1——protocol 通过保存的 transport 发送数据,transport 通过回调驱动 protocol,二者共同构成一套面向网络与进程间 I/O 的抽象接口;面向连接的 event loop 方法(
create_connection一族)接受protocol_factory并返回(transport, protocol)元组,整篇接口文档都围绕这条 1:1 契约展开。
本文所有接口方法、回调语义与状态机均忠实对应 Doc/library/asyncio-protocol.rst,实现细节则可沿 Lib/asyncio/transports.py、Lib/asyncio/protocols.py、Lib/asyncio/selector_events.py 与 Lib/asyncio/base_events.py 按图索骥、继续深挖。