"sys.monitoring" --- Execution event monitoring
***********************************************

Added in version 3.12.

======================================================================

备注:

  "sys.monitoring" 是 "sys" 模块内部的一个命名空间，而不是一个独立模块
  ，因此不需要 "import sys.monitoring"，只要简单地 "import sys" 然后使
  用 "sys.monitoring"。

这个命名空间提供了对于激活和控制事件监控所需的函数和常量的访问。

在程序执行过程中，会发生对于监控执行的工具来说值得关注的事件。
"sys.monitoring" 命名空间提供了在相应事件发生时接收回调的操作方式。

monitoring API由三个部分组成：

* Tool identifiers

* Events

* 回调


工具标识符
==========

工具标识符是一个整数及其所关联的名称。 工具标识符被用来防止工具之间的
相互干扰并允许同时操作多个工作。 目前工具是完全独立的且不能被用于相互
监控。 这一限制在将来可能会被取消。

在注册或激活事件之前，工具应选择一个标识符。 标识符是 0 到 5 的开区间
内的整数。


注册和使用工具
--------------

sys.monitoring.use_tool_id(tool_id: int, name: str, /) -> None

   必须在 *tool_id* 可被使用之前调用。 *tool_id* 必须在 0 到 5 的开区
   间内。 如果 *tool_id* 已被使用则会引发 "ValueError"。

sys.monitoring.free_tool_id(tool_id: int, /) -> None

   应当在一个工具不再需要 *tool_id* 时被调用。

备注:

  "free_tool_id()" 将不会禁用关联到 *tool_id* 的全局或局部事件，也不会
  注销任何回调函数。 此函数仅被设计用来通知虚拟机特定的 *tool_id* 已不
  再被使用。

sys.monitoring.get_tool(tool_id: int, /) -> str | None

   如果 *tool_id* 已被使用则返回工具名称，否则返回 "None"。 *tool_id*
   取值必须在 0 至 5 的开区间内。

虚拟机在处理事件时对所有 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 并尊重其他工具的设置。


事件
====

以下事件是受支持的：

sys.monitoring.events.BRANCH

   条件分支被采用（或不采用）。

sys.monitoring.events.CALL

   Python 代码中的调用（事件发生在调用之前）。

sys.monitoring.events.C_RAISE

   从任意可调用对象引发的异常。 Python 函数除外（事件发生在退出之后）
   。

sys.monitoring.events.C_RETURN

   从任意可调用对象返回，Python 函数除外（事件在返回之后发生）。

sys.monitoring.events.EXCEPTION_HANDLED

   一个异常被处理。

sys.monitoring.events.INSTRUCTION

   一个 VM 指令即将被执行。

sys.monitoring.events.JUMP

   在控制流图中进行一次无条件的跳转。

sys.monitoring.events.LINE

   一条与之前指令行号不同的指令即将被执行。

sys.monitoring.events.PY_RESUME

   恢复执行一个 Python 函数（用于生成器和协程函数），"throw()" 调用除
   外。

sys.monitoring.events.PY_RETURN

   从一个 Python 函数返回（在返回之前立即发生，被调用方的帧将在栈中）
   。

sys.monitoring.events.PY_START

   开始一个 Python 函数（在调用之后立即发生，被调用方的帧将在栈中）

sys.monitoring.events.PY_THROW

   一个 Python 函数由 "throw()" 调用恢复执行。

sys.monitoring.events.PY_UNWIND

   在异常解除期间从一个 Python函数退出。

sys.monitoring.events.PY_YIELD

   从一个 Python 函数产出数据（在产出之前立即发生，被调用方的帧将在栈
   中）。

sys.monitoring.events.RAISE

   一个异常被引发，导致 "STOP_ITERATION" 事件的异常除外。

sys.monitoring.events.RERAISE

   一个异常被重新引发，例如在 "finally" 代码块结束的时候。

sys.monitoring.events.STOP_ITERATION

   一个 "StopIteration" 被人工引发；参见 the STOP_ITERATION event。

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

这些事件都是 "sys.monitoring.events" 命名空间的属性。 每个事件用整数常
量的 2 次幂来表示。 要定义一组事件，只需对多个单独事件执行按位或运算即
可。 例如，要同时指定 "PY_RETURN" 和 "PY_START" 事件，则使用表达式
"PY_RETURN | PY_START"。

sys.monitoring.events.NO_EVENTS

   An alias for "0" so users can do explicit comparisons like:

      if get_events(DEBUGGER_ID) == NO_EVENTS:
          ...

事件被分为三组：


本地事件
--------

本地事件与程序的正常执行相关联并且发生在明确定义的位置上。 所有本地事
件都可以被禁用。 本地事件包括：

* "PY_START"

* "PY_RESUME"

* "PY_RETURN"

* "PY_YIELD"

* "CALL"

* "LINE"

* "INSTRUCTION"

* "JUMP"

* "BRANCH"

* "STOP_ITERATION"


辅助事件
--------

辅助事件可以像其他事件一样被监视，但是由另一个事件来控制：

* "C_RAISE"

* "C_RETURN"

"C_RETURN" 和 "C_RAISE" 事件是由 "CALL" 事件控制的。 "C_RETURN" 和
"C_RAISE" 事件只会在相应的 "CALL" 事件被监控时才能被看到。


其他事件
--------

其他事件不一定与程序中的特定位置相关联并且不能被单独禁用。

可以被监视的其他事件包括：

* "PY_THROW"

* "PY_UNWIND"

* "RAISE"

* "EXCEPTION_HANDLED"


STOP_ITERATION 事件
-------------------

**PEP 380** 规定了当从生成器或协程返回值时可引发 "StopIteration" 异常
。 不过，这是一种非常低效的返回值的方式，因此某些 Python 实现，比如
CPython 3.12+，只有在异常对其他代码可见时才会引发它。

为允许工具监视真正的异常而不会拖慢生成器和协程的运行，解释器提供了
"STOP_ITERATION" 事件。 "STOP_ITERATION" 可以被局部禁用，这与 "RAISE"
不同。


开启和关闭事件
==============

要监视一个事件，它必须被开启并注册相应的回调函数。 可以通过将事件设置
为全局的或针对特定代码对象的来开启或关闭事件。


全局设置事件
------------

通过修改被监视的事件集可以对事件进行全局控制。

sys.monitoring.get_events(tool_id: int, /) -> int

   返回代表所有活动事件的 "int"。

sys.monitoring.set_events(tool_id: int, event_set: int, /) -> None

   激活在 *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, /) -> None

   激活在 *event_set* 中设置的针对 *code* 的所有局部事件。 如果
   *tool_id* 未被使用则会引发 "ValueError"。

局部事件将添加到全局事件中，但不会屏蔽全局事件。 换句话说，所有全局事
件都会为代码对象触发，无论是否有局部事件。


禁用事件
--------

sys.monitoring.DISABLE

   一个可从回调函数返回以禁用当前代码位置上的事件的特殊值。

可从回调函数返回 "sys.monitoring.DISABLE" 以禁用特定代码位置上的局部事
件。 这不会改变已设置的事件，也不会改变同一事件的任何其他代码位置。

禁用特定位置的事件对高性能的监控非常重要。 例如，如果调试器禁用了除几
个断点外的所有监控那么程序在调试器下运行时就不会产生额外的开销。

sys.monitoring.restart_events() -> None

   启用 "sys.monitoring.DISABLE" 针对所有工具禁用的所有事件。


注册回调函数
============

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

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

   使用给定的 *tool_id* 为 *event* 注册可调用对象 *func*

   如果已经为给定的 *tool_id* 和 *event* 注册了另一个回调，它将被注销
   并返回。 在其他情况下 "register_callback()" 将返回 "None"。

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

回调函数可在任何时候被注册或注销。

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


回调函数参数
------------

sys.monitoring.MISSING

   一个传给回调函数表明该调用不附带任何参数的特殊值。

当一个激活的事件发生时，已注册的回调函数将被调用。 不同的事件将为回调
函数提供不同的参数，如下所示：

* "PY_START" 和 "PY_RESUME":

     func(code: CodeType, instruction_offset: int) -> DISABLE | Any

* "PY_RETURN" 和 "PY_YIELD":

     func(code: CodeType, instruction_offset: int, retval: object) -> DISABLE | Any

* "CALL", "C_RAISE" 和 "C_RETURN":

     func(code: CodeType, instruction_offset: int, callable: object, arg0: object | MISSING) -> DISABLE | Any

  如果没有任何参数，则 *arg0* 将被设为 "sys.monitoring.MISSING"。

* "RAISE", "RERAISE", "EXCEPTION_HANDLED", "PY_UNWIND", "PY_THROW" 和
  "STOP_ITERATION":

     func(code: CodeType, instruction_offset: int, exception: BaseException) -> DISABLE | Any

* "LINE":

     func(code: CodeType, line_number: int) -> DISABLE | Any

* "BRANCH" 和 "JUMP":

     func(code: CodeType, instruction_offset: int, destination_offset: int) -> DISABLE | Any

  请注意 *destination_offset* 是代码下一次执行的位置。 对于未进入的分
  支这将为该分支之后的指令的偏移量。

* "INSTRUCTION":

     func(code: CodeType, instruction_offset: int) -> DISABLE | Any
