事件

当代码对象执行时，会发生各种事件，这些事件可能对工具有用。通过激活事件并注册回调函数，工具可以以任何适合它们的方式响应这些事件。事件可以全局设置，也可以针对各个代码对象设置。

对于 3.12，CPython 将支持以下事件

• PY_START: Python 函数的开始（在调用后立即发生，被调用者的帧将在栈上）
• PY_RESUME: Python 函数的恢复（对于生成器和协程函数），除了 throw() 调用。
• PY_THROW: Python 函数通过 throw() 调用恢复。
• PY_RETURN: 从 Python 函数返回（在返回前立即发生，被调用者的帧将在栈上）。
• PY_YIELD: 从 Python 函数生成（在生成前立即发生，被调用者的帧将在栈上）。
• PY_UNWIND: 在异常展开期间退出 Python 函数。
• CALL: Python 代码中的调用（事件发生在调用之前）。
• C_RETURN: 从任何可调用对象返回，除了 Python 函数（事件发生在返回之后）。
• C_RAISE: 从任何可调用对象引发的异常，除了 Python 函数（事件发生在退出之后）。
• RAISE: 引发异常，除了导致 STOP_ITERATION 事件的异常。
• EXCEPTION_HANDLED: 处理异常。
• LINE: 将要执行的指令的行号与前一个指令不同。
• INSTRUCTION – 将要执行的虚拟机指令。
• JUMP – 执行控制流图中的无条件跳转。
• BRANCH – 执行条件分支（或不执行）。
• STOP_ITERATION – 引发人工 StopIteration；请参阅 STOP_ITERATION 事件。

将来可能会添加更多事件。

所有事件都将是 sys.monitoring 中 events 命名空间的属性。所有事件都将用 2 的幂整数表示，以便它们可以与 | 运算符结合使用。

事件分为三组

工具标识符

虚拟机可以同时支持最多 6 个工具。在注册或激活事件之前，工具应该选择一个标识符。标识符是 0 到 5 范围内的整数。

sys.monitoring.use_tool_id(id, name:str) -> None
sys.monitoring.free_tool_id(id) -> None
sys.monitoring.get_tool(id) ->  str | None

sys.monitoring.use_tool_id 如果 id 正在使用，则会引发 ValueError。sys.monitoring.get_tool 如果 id 正在使用，则返回工具的名称，否则返回 None。

所有 ID 在虚拟机中关于事件的处理方式都相同，但以下 ID 是预定义的，以便于工具之间的协作

sys.monitoring.DEBUGGER_ID = 0
sys.monitoring.COVERAGE_ID = 1
sys.monitoring.PROFILER_ID = 2
sys.monitoring.OPTIMIZER_ID = 5

没有义务设置 ID，也没有任何东西可以阻止工具使用 ID，即使它已经被使用。但是，鼓励工具使用唯一的 ID 并尊重其他工具。

例如，如果调试器已附加并且 DEBUGGER_ID 正在使用，它应该报告错误，而不是继续不管。

OPTIMIZER_ID 是为像 Cinder 或 PyTorch 这样的工具提供的，这些工具想要优化 Python 代码，但需要以某种依赖于更广泛上下文的方式来决定优化什么。

全局设置事件

可以通过修改正在监控的事件集来全局控制事件

• sys.monitoring.get_events(tool_id:int)->int 返回表示所有活动事件的 int。
• sys.monitoring.set_events(tool_id:int, event_set: int) 激活 event_set 中设置的所有事件。如果 tool_id 未在使用，则会引发 ValueError。

默认情况下，没有事件处于活动状态。

每个代码对象的事件

事件也可以在每个代码对象的基础上进行控制

• sys.monitoring.get_local_events(tool_id:int, code: CodeType)->int 返回 code 的所有本地事件
• sys.monitoring.set_local_events(tool_id:int, code: CodeType, event_set: int) 激活 code 的所有本地事件，这些事件在 event_set 中设置。如果 tool_id 未在使用，则会引发 ValueError。

本地事件会添加到全局事件中，但不会覆盖它们。换句话说，无论本地事件如何，所有全局事件都会对代码对象触发。

注册回调函数

要为事件注册一个可调用对象，请调用

sys.monitoring.register_callback(tool_id:int, event: int, func: Callable | None) -> Callable | None

如果另一个回调函数已为给定的 tool_id 和 event 注册，则将其注销并返回。否则，register_callback 返回 None。

可以通过调用 sys.monitoring.register_callback(tool_id, event, None) 来注销函数。

回调函数可以随时注册和注销。

注册或注销回调函数将生成一个 sys.audit 事件。

回调函数中的事件

事件在注册该回调函数的工具的回调函数及其被调用者中被挂起。

这意味着其他工具将在其他工具的回调函数中看到事件。这对于调试性能分析工具可能很有用，但会产生误导性的性能分析结果，因为调试器工具将显示在性能分析结果中。

事件顺序

如果一条指令触发多个事件，则按以下顺序发生

• LINE
• INSTRUCTION
• 所有其他事件（每条指令只能发生其中一个事件）

每个事件都按 ID 升序传递给工具。

“call” 事件组

大多数事件是独立的；设置或禁用一个事件不会影响其他事件。但是，CALL、C_RAISE 和 C_RETURN 事件形成一个组。如果设置或禁用了这些事件中的任何一个，则该组中的所有事件都会受到影响。禁用 CALL 事件不会禁用匹配的 C_RAISE 或 C_RETURN，但会禁用所有后续事件。

sys.monitoring 命名空间的属性

• def use_tool_id(id)->None
• def free_tool_id(id)->None
• def get_events(tool_id: int)->int
• def set_events(tool_id: int, event_set: int)->None
• def get_local_events(tool_id: int, code: CodeType)->int
• def set_local_events(tool_id: int, code: CodeType, event_set: int)->None
• def register_callback(tool_id: int, event: int, func: Callable)->Optional[Callable]
• def restart_events()->None
• DISABLE: object
• MISSING: object

访问“仅限调试”功能

标准库的一些功能对于普通代码不可访问，但对于调试器可以访问。例如，设置局部变量或行号。

这些功能将可用于回调函数。

性能

如果没有任何事件处于活动状态，则此 PEP 应该对性能产生轻微的积极影响。实验表明，由于不支持直接使用 sys.settrace()，速度提高了 1% 到 2%。

sys.settrace() 的性能将大致相同。 sys.setprofile() 的性能应该会更好。但是，依赖于 sys.settrace() 和 sys.setprofile() 的工具可以通过使用此 PEP 提供的 API 来大幅提高速度。

如果只有一小部分事件处于活动状态，例如调试器，则回调的开销将比 sys.settrace() 小几个数量级，并且比使用 PEP 523 便宜得多。

覆盖工具可以通过在所有回调中返回 DISABLE 来以非常低的成本实现。

对于大量使用 instrumentation 的代码（例如，使用 LINE），性能应该优于 sys.settrace，但不会好太多，因为性能将主要受回调中花费的时间影响。

对于优化虚拟机，例如 CPython 的未来版本（以及 PyPy 如果它们选择支持此 API），在长时间运行的程序中间更改活动事件集可能会非常昂贵，可能需要数百毫秒，因为它会触发反优化。一旦发生这种反优化，性能应该会恢复，因为虚拟机可以重新优化 instrumentation 代码。

通常，这些操作可以被认为是快速的

• def get_events(tool_id: int)->int
• def get_local_events(tool_id: int, code: CodeType)->int
• def register_callback(tool_id: int, event: int, func: Callable)->Optional[Callable]
• def get_tool(tool_id) -> str | None

这些操作较慢，但并不特别慢

• def set_local_events(tool_id: int, code: CodeType, event_set: int)->None

并且这些操作应该被视为缓慢的

• def use_tool_id(id, name:str)->None
• def free_tool_id(id)->None
• def set_events(tool_id: int, event_set: int)->None
• def restart_events()->None

缓慢操作的速度取决于它们发生的时间。如果在程序的早期，在模块加载之前完成，它们应该相当便宜。

调试器

覆盖率工具

覆盖率工具需要跟踪控制图的哪些部分已执行。为此，它们需要注册 PY_ 事件以及 JUMP 和 BRANCH 事件。

然后，可以在执行完成后将此信息转换回基于行的报告。

分析器

简单的分析器需要收集有关调用的信息。为此，分析器应注册以下事件

• PY_START
• PY_RESUME
• PY_THROW
• PY_RETURN
• PY_YIELD
• PY_UNWIND
• CALL
• C_RAISE
• C_RETURN