KBEngine 内嵌 Python 3.7 的 asyncio 事件循环策略(Policies)完全指南:从 API 到子进程监视器源码级解析

原创2026-10-17 20:37:101,421 阅读
文章标签:游戏开发后端

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 创建。

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())

结合前文源码可知这个示例的实际效果:

  1. DefaultEventLoopPolicy(Unix 下为 _UnixDefaultEventLoopPolicy)继承自 BaseDefaultEventLoopPolicy,其 get_event_loop() 内部逻辑是:主线程且未设置过循环时自动 set_event_loop(new_event_loop()),否则若无循环抛出 RuntimeError(见 events.py#L632-L646);
  2. 子类先 super().get_event_loop() 获得当前线程的循环,再对 loop 做自定义处理(例如包装、埋点、监控),最后返回;
  3. 通过 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。
登录后查看全文
kbengine