gh-141004: Document unstable perf map functions in `ceval.h` (GH-143492)

diff --git a/Doc/c-api/perfmaps.rst b/Doc/c-api/perfmaps.rst
index bd05e628faaaa10de43ed2fa50229331efba4beb..a962c4ee09ad77de8c14a63910eeabae19d99b62 100644 (file)
--- a/Doc/c-api/perfmaps.rst
+++ b/Doc/c-api/perfmaps.rst
@@ -49,3 +49,43 @@ Note that holding an :term:`attached thread state` is not required for these API
    This is called by the runtime itself during interpreter shut-down. In
    general, there shouldn't be a reason to explicitly call this, except to
    handle specific scenarios such as forking.
+
+.. c:function:: int PyUnstable_CopyPerfMapFile(const char *parent_filename)
+
+   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.
+
+   .. versionadded:: 3.13
+
+.. c:function:: int PyUnstable_PerfTrampoline_CompileCode(PyCodeObject *code)
+
+   Compile the given code object using the current perf trampoline.
+
+   The "current" trampoline is the one set by the runtime or the most recent
+   :c:func:`PyUnstable_PerfTrampoline_SetPersistAfterFork` call.
+
+   If no trampoline is set, falls back to normal compilation (no perf map entry).
+
+   :param code: The code object to compile.
+   :return: 0 on success, -1 on failure.
+
+   .. versionadded:: 3.13
+
+.. c:function:: int PyUnstable_PerfTrampoline_SetPersistAfterFork(int enable)
+
+   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).
+
+   :param enable: 1 to enable, 0 to disable.
+   :return: 0 on success, -1 on failure.
+
+   .. versionadded:: 3.13

diff --git a/Tools/check-c-api-docs/ignored_c_api.txt b/Tools/check-c-api-docs/ignored_c_api.txt
index dfec0524cfe016deca1e8eea6ec235c1c06fb430..fa53b205c4ff6afed09e648aacc8370f147205ba 100644 (file)
--- a/Tools/check-c-api-docs/ignored_c_api.txt
+++ b/Tools/check-c-api-docs/ignored_c_api.txt
@@ -43,10 +43,6 @@ PyDescr_TYPE
 PyWrapperFlag_KEYWORDS
 # cpython/fileobject.h
 Py_UniversalNewlineFgets
-# cpython/ceval.h
-PyUnstable_CopyPerfMapFile
-PyUnstable_PerfTrampoline_CompileCode
-PyUnstable_PerfTrampoline_SetPersistAfterFork
 # cpython/pyframe.h
 PyUnstable_EXECUTABLE_KINDS
 PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION