事件

當程式碼物件執行時，會發生各種工具可能感興趣的事件。透過啟用事件並註冊回呼函式，工具可以用任何適合的方式回應這些事件。事件可以全域設定，也可以針對個別程式碼物件設定。

對於 3.12 版本，CPython 將支援以下事件

• PY_START: Python 函式的開始（在呼叫後立即發生，被呼叫者的框架將在堆疊上）
• PY_RESUME: Python 函式的恢復（針對產生器和協程函式），除了 throw() 呼叫之外。
• PY_THROW: Python 函式透過 throw() 呼叫恢復。
• PY_RETURN: 從 Python 函式返回（在返回前立即發生，被呼叫者的框架將在堆疊上）。
• PY_YIELD: 從 Python 函式生成 (Yield)（在生成前立即發生，被呼叫者的框架將在堆疊上）。
• PY_UNWIND: 在異常展開期間退出 Python 函式。
• CALL: Python 程式碼中的呼叫（事件在呼叫前發生）。
• C_RETURN: 從任何可呼叫物件（Python 函式除外）返回（事件在返回後發生）。
• C_RAISE: 從任何可呼叫物件（Python 函式除外）引發異常（事件在退出後發生）。
• RAISE: 引發異常，但導致 STOP_ITERATION 事件的異常除外。
• EXCEPTION_HANDLED: 異常已被處理。
• LINE: 即將執行的指令與上一條指令的行號不同。
• INSTRUCTION: 即將執行虛擬機器 (VM) 指令。
• JUMP: 控制流程圖中發生無條件跳轉。
• BRANCH: 發生條件分支（無論是否執行）。
• STOP_ITERATION: 引發人工的 StopIteration；參見 STOP_ITERATION 事件。

未來可能會新增更多事件。

所有事件都將是 sys.monitoring 中 events 命名空間的屬性。所有事件皆以 2 的冪次方整數表示，以便可以使用 | 運算子進行組合。

事件分為三類

工具識別碼

VM 一次最多支援 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

若 id 正在使用中，sys.monitoring.use_tool_id 會引發 ValueError。若 id 正在使用中，sys.monitoring.get_tool 會回傳該工具名稱，否則回傳 None。

就事件而言，所有 ID 對 VM 來說都是一視同仁的，但以下 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，可以以極低的成本實作覆蓋率工具。

對於高度檢測 (instrumented) 的程式碼（例如使用 LINE），效能應優於 sys.settrace，但不會好太多，因為效能將受限於回呼中所花費的時間。

對於最佳化虛擬機器，例如未來版本的 CPython（以及 PyPy 若選擇支援此 API），在長執行程式的中途更改活動事件集合可能相當昂貴，可能會花費數百毫秒，因為這會觸發去最佳化 (de-optimization)。一旦發生此類去最佳化，隨著 VM 重新最佳化被檢測程式碼，效能應會恢復。

一般而言，這些操作可以視為快速的

• 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。

這些資訊可以在執行完成後轉換為基於行的報告。

效能分析器 (Profiler)

簡單的效能分析器需要收集有關呼叫的資訊。為此，效能分析器應註冊以下事件：

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