對 Perf Map 的支援

在支援的平台上（截至撰寫本文時，僅限 Linux），runtime 可以利用 perf map 檔案使得外部分析工具（例如 perf）可以見到 Python 函式。正在運行的行程可能會在 /tmp 目錄中建立一個檔案，其中包含可以將一段可執行程式碼對映到名稱的各個條目。此介面在 Linux Perf 工具的文件中有被描述。

在 Python 中，這些輔助 API 可以被依賴於運行期間 (on the fly) 產生機器碼的函式庫和功能所使用。

請注意，這些 API 不需要持有 attached thread state。

int PyUnstable_PerfMapState_Init(void)
這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。

打開 /tmp/perf-$pid.map 檔案，除非它已經打開，並建立一個鎖以確保執行緒安全地 (thread-safe) 寫入該檔案（前提是寫入是透過 PyUnstable_WritePerfMapEntry() 完成的）。通常不需要明確地呼叫它；只需使用 PyUnstable_WritePerfMapEntry() 它就會在首次呼叫時初始化狀態。

建立/打開 perf map 檔案成功時回傳 0，失敗時回傳 -1，建立鎖時失敗則回傳 -2。檢查 errno 以取得更多造成失敗的資訊。

int PyUnstable_WritePerfMapEntry(const void *code_addr, unsigned int code_size, const char *entry_name)
這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。

將單一條目寫入 /tmp/perf-$pid.map 檔案。此函式是執行緒安全的。以下是一個條目的範例：

# 位址        大小  名稱
7f3529fcf759 b     py::bar:/run/t.py

如果尚未開啟 perf map 檔案，將在寫入條目之前呼叫 PyUnstable_PerfMapState_Init()。成功時回傳 0，失敗時回傳與 PyUnstable_PerfMapState_Init() 失敗時相同的錯誤碼。

void PyUnstable_PerfMapState_Fini(void)
這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。

關閉由 PyUnstable_PerfMapState_Init() 開啟的 perf map 檔案，這是在直譯器關閉期間由 runtime 本身呼叫的。一般來說，除了處理 forking 等特定場景外，不應該明確地呼叫它。

int PyUnstable_CopyPerfMapFile(const char *parent_filename)
這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。

Open the /tmp/perf-$pid.map file and append the content of parent_filename to it.

This function is available on all platforms but only generates output on platforms that support perf maps (currently only Linux). On other platforms, it does nothing.

在 3.13 版被加入.

int PyUnstable_PerfTrampoline_CompileCode(PyCodeObject *code)
這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。

Compile the given code object using the current perf trampoline.

The "current" trampoline is the one set by the runtime or the most recent PyUnstable_PerfTrampoline_SetPersistAfterFork() call.

If no trampoline is set, falls back to normal compilation (no perf map entry).

參數:

  • code -- The code object to compile.

回傳:

0 on success, -1 on failure.

在 3.13 版被加入.

int PyUnstable_PerfTrampoline_SetPersistAfterFork(int enable)
這是 不穩定 API，它可能在小版本發布中沒有任何警告地被變更。

Set whether the perf trampoline should persist after a fork.

  • If enable is true (non-zero): perf map file remains open/valid post-fork. Child process inherits all existing perf map entries.

  • If enable is false (zero): perf map closes post-fork. Child process gets empty perf map.

Default: false (clears on fork).

參數:

  • enable -- 1 to enable, 0 to disable.

回傳:

0 on success, -1 on failure.

在 3.13 版被加入.