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

(cherry picked from commit 6453065db9ff31e3f737240030f8311d2b087851)

Co-authored-by: Yashraj <yashrajpala8@gmail.com>

diff --git a/Doc/c-api/perfmaps.rst b/Doc/c-api/perfmaps.rst
index 3d44d2eb6bf41d6b04f8af6bfbc3f97eebfe092f..11a00917dfa8c2b40a360e8f0eb1cf532b11ca1f 100644 (file)
--- a/Doc/c-api/perfmaps.rst
+++ b/Doc/c-api/perfmaps.rst
@@ -48,3 +48,43 @@ Note that holding the Global Interpreter Lock (GIL) is not required for these AP
    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 553e88c7fca8b772d03d5ddc845cdc6991850607..e557c0aff26eb483b00d2eab61e9cb9419b5124f 100644 (file)
--- a/Tools/check-c-api-docs/ignored_c_api.txt
+++ b/Tools/check-c-api-docs/ignored_c_api.txt
@@ -60,20 +60,6 @@ PyWrapperFlag_KEYWORDS
 PyFile_NewStdPrinter
 PyStdPrinter_Type
 Py_UniversalNewlineFgets
-# cpython/setobject.h
-PySet_MINSIZE
-# cpython/ceval.h
-PyUnstable_CopyPerfMapFile
-PyUnstable_PerfTrampoline_CompileCode
-PyUnstable_PerfTrampoline_SetPersistAfterFork
-# cpython/genobject.h
-PyAsyncGenASend_CheckExact
-# cpython/longintrepr.h
-PyLong_BASE
-PyLong_MASK
-PyLong_SHIFT
-# cpython/pyerrors.h
-PyException_HEAD
 # cpython/pyframe.h
 PyUnstable_EXECUTABLE_KINDS
 PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION
@@ -142,3 +128,10 @@ PyUnicode_IS_READY
 PYTHON_ABI_VERSION
 PySequence_In
 PYOS_STACK_MARGIN
+# Soft-deprecated in 3.14; will remain undocumented in 3.13
+PySet_MINSIZE
+PyAsyncGenASend_CheckExact
+PyLong_BASE
+PyLong_MASK
+PyLong_SHIFT
+PyException_HEAD