KBEngine 内嵌 Python 3.7 的 asyncio 事件循环策略(Policies)完全指南:从 API 到子进程监视器源码级解析
KBEngine 内嵌 Python 3.7 的 asyncio 事件循环策略(Policies)完全指南:从 API 到子进程监视器源码级解析
本文以仓库内嵌 Python 3.7.3 官方文档 asyncio-policy.rst 为骨架,系统讲解 asyncio 的事件循环策略(Event Loop Policy) 机制:如何获取/设置进程级策略、AbstractEventLoopPolicy 抽象基类、内置策略(DefaultEventLoopPolicy、WindowsProactorEventLoopPolicy)、Unix 子进程监视器(SafeChildWatcher/FastChildWatcher)以及自定义策略的写法。读完本文,你将掌握策略与事件循环、线程上下文的关系,能针对多线程与子进程场景正确选择或定制策略,并理解策略在 Lib/asyncio 源码中的落地实现。
一、事件循环策略(Policy)是什么
策略(Policy)是一个进程级(per-process)的全局对象,负责事件循环的管理与分配。 每个事件循环都有一个默认策略,可以通过策略 API 更换和定制。
- 策略定义了"上下文(context)"的概念,并为每个上下文维护一个独立的事件循环;
- 默认策略将"上下文"定义为"当前线程",即每个线程持有自己的事件循环;
- 通过自定义策略,可以定制 get_event_loop、set_event_loop、new_event_loop 三个函数的行为;
- 策略对象应当实现 AbstractEventLoopPolicy 抽象基类定义的接口。
从源码结构看,策略机制的核心位于 Lib/asyncio/events.py:events.py 中维护了一个全局的 _event_loop_policy 变量(第 667 行),初始为 None,并在首次调用 get_event_loop_policy() 时通过 _init_event_loop_policy() 惰性创建默认策略(第 715-720 行),同时用 threading.Lock 保护并发创建。
二、获取与设置策略:get_event_loop_policy / set_event_loop_policy
asyncio.get_event_loop_policy() # 返回当前进程级策略
asyncio.set_event_loop_policy(policy) # 将进程级策略设置为 policy
关键行为(与 events.py 源码一致):
get_event_loop_policy():返回当前进程级策略。若从未设置过,会自动实例化DefaultEventLoopPolicy并返回;set_event_loop_policy(policy):若传入None,则恢复默认策略;- 传入非
None的 policy 时,源码使用assert policy is None or isinstance(policy, AbstractEventLoopPolicy)进行类型校验。
由于策略对象是进程级全局的,它的生效范围覆盖进程内所有线程;而"每线程一个事件循环"只是默认策略的分配规则,并非策略机制本身的限制——自定义策略完全可以实现"单一全局事件循环"或"其他上下文定义"。
三、AbstractEventLoopPolicy:策略必须实现的抽象接口
AbstractEventLoopPolicy 是 asyncio 策略的抽象基类,定义于 Lib/asyncio/events.py#L576-L607,包含以下抽象方法:
| 方法 | 职责 | 约束 |
|---|---|---|
get_event_loop() |
获取当前上下文的事件循环 | 返回实现 AbstractEventLoop 接口的循环对象,绝不允许返回 None;若当前上下文没有设置循环且策略不允许自动创建,应抛出异常(3.6 起行为有版本变化) |
set_event_loop(loop) |
将当前上下文的事件循环设为 loop |
无 |
new_event_loop() |
创建并返回一个新的事件循环对象 | 返回的循环对象绝不允许为 None;若需使其成为当前上下文的循环,须显式调用 set_event_loop |
get_child_watcher() |
获取子进程监视器对象 | 返回实现 AbstractChildWatcher 接口的对象,仅 Unix 平台可用 |
set_child_watcher(watcher) |
设置当前子进程监视器 | 仅 Unix 平台可用 |
值得注意的是,源码中这 5 个方法全部直接 raise NotImplementedError,说明策略的具体行为完全由子类决定。这也解释了为什么官方文档建议自定义策略时以 DefaultEventLoopPolicy 为基类而非直接实现该抽象类。
四、内置策略:DefaultEventLoopPolicy 与 WindowsProactorEventLoopPolicy
asyncio 自带以下内置策略:
4.1 DefaultEventLoopPolicy(默认策略)
- 在 Unix 与 Windows 平台上均使用
SelectorEventLoop实现; - 无需手动安装,asyncio 自动配置为使用默认策略。
对应源码(以仓库内 Python 3.7.3 为例):
- Unix 平台:Lib/asyncio/unix_events.py#L1089-L1141 定义
_UnixDefaultEventLoopPolicy,_loop_factory = _UnixSelectorEventLoop,并在模块末尾执行DefaultEventLoopPolicy = _UnixDefaultEventLoopPolicy; - Windows 平台:Lib/asyncio/windows_events.py#L832-L840 定义
WindowsSelectorEventLoopPolicy(_loop_factory = SelectorEventLoop)与WindowsProactorEventLoopPolicy(_loop_factory = ProactorEventLoop),并在 3.7 版本中将DefaultEventLoopPolicy指向WindowsSelectorEventLoopPolicy; - Lib/asyncio/init.py#L38-L43 根据
sys.platform == 'win32'决定从windows_events还是unix_events导入DefaultEventLoopPolicy。
也就是说,本仓库内嵌的 Python 3.7.3 中,Windows 平台的默认策略同样是 Selector 实现;而 WindowsProactorEventLoopPolicy 是备选策略,用于启用基于 IOCP 的 ProactorEventLoop。
4.2 默认策略的线程语义(源码级细节)
BaseDefaultEventLoopPolicy(events.py#L610-L660)用 threading.local 实现了"每线程一个事件循环":
- 每个线程通过
self._local._loop持有自己的循环对象,_set_called标记是否显式设置过; - 只有主线程(
threading._MainThread)在未设置循环时会自动创建;其他线程若未显式set_event_loop,调用get_event_loop()会抛出RuntimeError: There is no current event loop in thread ...; set_event_loop(loop)会断言loop is None or isinstance(loop, AbstractEventLoop);new_event_loop()直接调用self._loop_factory()创建新循环,且不会自动绑定到当前线程。
4.3 WindowsProactorEventLoopPolicy(Windows 备选策略)
- 使用
ProactorEventLoop事件循环实现(基于 Windows I/O 完成端口 IOCP); - 仅适用于 Windows 平台。
源码中 ProactorEventLoop 定义于 Lib/asyncio/windows_events.py#L303-L309,默认使用 IocpProactor。在 Windows 上需要 Proactor 特性(如更好的异步文件/管道支持)时,可按如下方式切换:
import asyncio
asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())
在 Windows 上也可以直接手动构造循环并设置(参考 asyncio-eventloop.rst 中的示例):
import asyncio
import sys
if sys.platform == 'win32':
loop = asyncio.ProactorEventLoop()
asyncio.set_event_loop(loop)
关于 SelectorEventLoop 与 ProactorEventLoop 两种循环实现的更多说明(含手动指定 selector 的用法),可参见 asyncio-eventloop.rst。
五、子进程监视器(Process Watchers):事件循环如何感知子进程退出
子进程监视器允许自定义事件循环在 Unix 上监控子进程的方式。 事件循环需要知道子进程何时退出。在 asyncio 中,子进程通过 asyncio.create_subprocess_exec 与 loop.subprocess_exec 创建。
- asyncio 定义了 AbstractChildWatcher 抽象基类,子进程监视器必须实现该接口;
- 提供了两种实现:
SafeChildWatcher(默认) 与FastChildWatcher; - 相关主题可进一步参考 asyncio-subprocess.rst 中的 Subprocess and Threads 一节。
5.1 获取与设置子进程监视器
asyncio.get_child_watcher() # 返回当前策略使用的子进程监视器
asyncio.set_child_watcher(watcher) # 为当前策略设置子进程监视器
set_child_watcher(watcher):watcher必须实现AbstractChildWatcher基类定义的方法;- 若当前策略尚未初始化监视器,Unix 默认策略的
get_child_watcher()会自动创建一个SafeChildWatcher(见 unix_events.py#L1119-L1127 的_init_watcher); - 注意:第三方事件循环实现可能不支持自定义子进程监视器。对于这类事件循环,调用
set_child_watcher可能被禁止或毫无效果。
5.2 AbstractChildWatcher 接口
AbstractChildWatcher 定义于 Lib/asyncio/unix_events.py#L769-L836,实现类必须提供以下方法:
| 方法 | 行为 |
|---|---|
add_child_handler(pid, callback, *args) |
注册子进程处理器:当 PID 为 pid 的进程终止时,安排调用 callback(pid, returncode, *args)。为同一进程再次指定回调会替换之前的处理器。callback 必须是线程安全的 |
remove_child_handler(pid) |
移除 PID 为 pid 的处理器。成功移除返回 True,没有可移除内容返回 False |
attach_loop(loop) |
将监视器绑定到某个事件循环;若之前已绑定到其他循环,会先解绑再绑定新循环。loop 可以为 None |
close() |
关闭监视器,必须调用以确保底层资源被清理 |
此外,AbstractChildWatcher 还定义了 __enter__/__exit__ 上下文管理器协议:启动新进程必须在 with watcher: 块内进行,以便监视器在进程完全注册前挂起活动(防止竞态条件)。源码 docstring 给出了典型用法:
with watcher:
proc = subprocess.Popen("sleep 1")
watcher.add_child_handler(proc.pid, callback)
源码还特别强调两点实现约束:实现类必须线程安全;由于监视器对象可能捕获 SIGCHLD 信号并调用 waitpid(-1),每个进程只能有一个活动的监视器对象。
5.3 基类 BaseChildWatcher:SIGCHLD 信号与 returncode 计算
两种内置实现都继承自 BaseChildWatcher(unix_events.py#L839-L897),公共逻辑包括:
attach_loop(loop):通过loop.add_signal_handler(signal.SIGCHLD, self._sig_chld)注册SIGCHLD信号处理器;解绑时移除信号处理器。若解绑时仍有未完成回调,会发出RuntimeWarning;- 绑定后立即调用
_do_waitpid_all(),避免子进程在切换期间已终止造成的竞态; _sig_chld()捕获SIGCHLD后遍历收割子进程,异常交由循环的call_exception_handler处理;_compute_returncode(status):被信号杀死返回-WTERMSIG(status)(负数表示被信号 N 终止,POSIX 语义),正常退出返回WEXITSTATUS(status)。
5.4 SafeChildWatcher:默认的"安全"实现
SafeChildWatcher 定义于 unix_events.py#L900-L976。
- 实现思路:不调用
os.waitpid(-1),而是在每次收到SIGCHLD信号时,对已注册的每个 PID 逐个显式轮询os.waitpid(pid, os.WNOHANG),因此不会干扰其他也在创建进程的代码; - 代价:处理大量子进程时开销显著——每次
SIGCHLD到来都是 O(n) 复杂度; - asyncio 默认使用此实现(Unix 默认策略在
_init_watcher中创建的就是SafeChildWatcher,见 unix_events.py#L1097-L1103)。
源码中的 _do_waitpid 处理了一个边界情况:若 os.waitpid 抛出 ChildProcessError(子进程已被其他代码收割),会以 returncode 255 上报并给出 warning 日志。
5.5 FastChildWatcher:低开销的"快速"实现
FastChildWatcher 定义于 unix_events.py#L979-L1086。
- 实现思路:直接调用
os.waitpid(-1, os.WNOHANG)一次性收割所有已终止子进程,因此处理大量子进程时没有明显开销——每个子进程终止时是 O(1); - 风险:可能"顺带"收割其他代码创建的进程并阻塞其等待,可能破坏其他也在创建进程并等待其结束的代码;
- 为降低风险,实现用
_lock与_forks计数维护with watcher:上下文,未注册 PID 的终止信息先暂存于_zombies,并在离开上下文时对未知 PID 给出 warning(源码中称之为 "collateral victims",即连带收割的进程)。
选择建议:默认使用 SafeChildWatcher 即可;当子进程数量极大且明确自己独占子进程管理权时,可考虑切换为 FastChildWatcher 换取 O(1) 性能。切换方式:
import asyncio
asyncio.get_child_watcher() # 先确保监视器已实例化(主线程中)
asyncio.set_child_watcher(asyncio.FastChildWatcher())
5.6 子进程与线程的协作限制
默认(Unix)策略下运行子进程存在如下限制(出自 asyncio-subprocess.rst#L293-L307 的 "Subprocess and Threads" 一节,与 _UnixDefaultEventLoopPolicy.set_event_loop 中"仅主线程才将循环附加到监视器"的源码逻辑一致):
- 事件循环必须运行在主线程;
- 在其他线程执行子进程之前,必须先在主线程调用
get_child_watcher()完成监视器实例化; - 替代事件循环实现可能不受上述限制,需查阅其各自文档。
六、自定义策略(Custom Policies)
官方文档推荐的实现方式是:继承 DefaultEventLoopPolicy,只覆盖需要定制行为的方法,而非直接实现抽象基类。文档给出的标准示例:
import asyncio
class MyEventLoopPolicy(asyncio.DefaultEventLoopPolicy):
def get_event_loop(self):
"""Get the event loop.
This may be None or an instance of EventLoop.
"""
loop = super().get_event_loop()
# Do something with loop ...
return loop
asyncio.set_event_loop_policy(MyEventLoopPolicy())
结合前文源码可知这个示例的实际效果:
DefaultEventLoopPolicy(Unix 下为_UnixDefaultEventLoopPolicy)继承自BaseDefaultEventLoopPolicy,其get_event_loop()内部逻辑是:主线程且未设置过循环时自动set_event_loop(new_event_loop()),否则若无循环抛出RuntimeError(见 events.py#L632-L646);- 子类先
super().get_event_loop()获得当前线程的循环,再对loop做自定义处理(例如包装、埋点、监控),最后返回; - 通过
asyncio.set_event_loop_policy(MyEventLoopPolicy())安装后,进程内后续所有get_event_loop()/new_event_loop()/set_event_loop()调用都会走该策略。
典型自定义场景(由源码结构与文档推导):需要为每个线程自动创建循环、需要单一全局循环、需要在创建循环时注入自定义实现(修改 _loop_factory)、或需要在子进程监视器层面做特殊管理(重写 get_child_watcher/set_child_watcher)。
七、实践要点小结
- 策略是进程级全局对象:
set_event_loop_policy(None)可随时恢复默认策略; - 默认策略按线程分配循环:只有主线程会自动创建循环,其他线程需显式
set_event_loop; - Windows 上可在 Selector 与 Proactor 策略间切换:
WindowsProactorEventLoopPolicy基于 IOCP,仅限 Windows; - Unix 子进程监视器默认是
SafeChildWatcher(O(n)/SIGCHLD,安全),大量子进程场景可换FastChildWatcher(O(1),但可能破坏其他进程创建代码); - 多线程中使用子进程:先在主线程
get_child_watcher()实例化监视器,事件循环须跑在主线程; - 相关官方文档与源码均可直接在仓库中查阅:asyncio-policy.rst、Lib/asyncio/events.py、Lib/asyncio/unix_events.py、Lib/asyncio/windows_events.py,以及配套的 asyncio-eventloop.rst 与 asyncio-subprocess.rst。