对 Perf Maps 的支持

On supported platforms (Linux and macOS), the runtime can take advantage of perf map files to make Python functions visible to an external profiling tool (such as perf or samply). A running process may create a file in the /tmp directory, which contains entries that can map a section of executable code to a name. This interface is described in the documentation of the Linux Perf tool.

在 Python 中，这些辅助 API 可供依赖于动态生成机器码的库和特性使用。

请注意这些 API 并不要求持有已附加的线程状态 attached thread state 。

int PyUnstable_PerfMapState_Init(void)

这是 不稳定 API。它可在次发布版中不经警告地改变。

打开 /tmp/perf-$pid.map 文件，除非它已经被打开，并创建一个锁来确保线程安全地写入该文件（如果写入是通过 PyUnstable_WritePerfMapEntry() 执行的）。 通常，没有必要显式地调用此函数；只需使用 PyUnstable_WritePerfMapEntry() 这样它将在第一次调用时初始化状态。

成功时返回 0，创建/打开 perf map 文件失败时返回 -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

将在写入条目之前调用 PyUnstable_PerfMapState_Init()，如果 perf map 文件尚未打开。 成功时返回 0，或者在失败时返回与 PyUnstable_PerfMapState_Init() 相同的错误代码。

void PyUnstable_PerfMapState_Fini(void)

这是 不稳定 API。它可在次发布版中不经警告地改变。

关闭 PyUnstable_PerfMapState_Init() 所打开的 perf map 文件。 此函数会在解释器关闭期间由运行时本身调用。 通常，应该没有理由显式地调用此函数，除了处理特殊场景例如分叉操作。