对 Perf Maps 的支持
*******************

On supported platforms (as of this writing, only Linux), the runtime
can take advantage of *perf map files* to make Python functions
visible to an external profiling tool (such as perf). 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 文件。 此函
   数会在解释器关闭期间由运行时本身调用。通常，应该没有理由显式地调用
   此函数，除了处理特殊场景例如分叉操作。
