gh-141004: Document unstable perf map functions in `ceval.h` by Yashp002 · Pull Request #143492 · python/cpython

Yashp002 · 2026-01-06T18:48:32Z

gh-141004: Document unstable perf map functions in ceval.h

This PR documents the PyUnstable_CopyPerfMapFile, PyUnstable_PerfTrampoline_CompileCode, and PyUnstable_PerfTrampoline_SetPersistAfterFork functions in Doc/c-api/perfmaps.rst.

📚 Documentation preview 📚: https://cpython-previews--143492.org.readthedocs.build/

StanFromIreland · 2026-01-06T18:49:48Z

Doc/c-api/frame.rst

   .. versionadded:: 3.12


+.. c:macro:: PyUnstable_EXECUTABLE_KIND_SKIP


You used the branch from the other PR, please remove these changes here.

I'm so sorry yes, fixing rn.

I hope it's not an issue if i force push a new branch over this one to fix my error?

In general, avoid them, in this case I think it is fine to remove the changes.

StanFromIreland · 2026-01-06T18:58:00Z

Doc/c-api/perfmaps.rst

+
+.. c:function:: int PyUnstable_CopyPerfMapFile(const char *parent_filename)
+
+   Open the ``/tmp/perf-$pid.map`` file and append the content of *parent_filename*


This should note what happens on Windows where this obviously won't work.

That's the case for all of these functions; the info should be in the beginning of the section.

This doesn't open the perf map file directly; it should use the same wording as PyUnstable_WritePerfMapEntry: “Will call :c:func:PyUnstable_PerfMapState_Init…”

@encukou Would this wording be suitable then as a replacement for line 56 as:

"Calls :c:func:PyUnstable_PerfMapState_Init if the perf map is not yet
initialized, then append the content of parent_filename to the perf map."

@encukou or @StanFromIreland Could you verify this one too?

I'd say only “Append contents of the file named parent_filename to the perf map.” in the opening paragraph, and add the note about _Init later (like in WritePerfMapEntry docs).

StanFromIreland · 2026-01-06T18:58:47Z

Doc/c-api/perfmaps.rst

+   Open the ``/tmp/perf-$pid.map`` file and append the content of *parent_filename*
+   to it.
+
+   :param parent_filename: The name of the file to copy.


Please don't use these (:param *: & :return:), like above use sentences.

encukou · 2026-01-08T12:30:23Z

Doc/c-api/perfmaps.rst

+
+.. c:function:: int PyUnstable_CopyPerfMapFile(const char *parent_filename)
+
+   Open the ``/tmp/perf-$pid.map`` file and append the content of *parent_filename*


I'd say only “Append contents of the file named parent_filename to the perf map.” in the opening paragraph, and add the note about _Init later (like in WritePerfMapEntry docs).

encukou · 2026-01-08T12:37:38Z

Doc/c-api/perfmaps.rst

+
+.. c:function:: int PyUnstable_PerfTrampoline_CompileCode(PyCodeObject *code)
+
+   Compile the given code object using the current perf trampoline.


What's the perf trampoline? How do you set the current one? What happens if there's no current trampoline?

encukou · 2026-01-08T12:40:05Z

Doc/c-api/perfmaps.rst

+
+.. c:function:: int PyUnstable_PerfTrampoline_SetPersistAfterFork(int enable)
+
+   Set whether the perf trampoline should persist after a fork.


This isn't very clear to me; could you add/link more explanation about the behaviour on fork?

ZeroIntensity

Please update Tools/check-c-api-docs/ignored_c_api.txt as well.

Yashp002 · 2026-01-08T18:07:20Z

@encukou , @ZeroIntensity

Docs unrelated to test failure

Tests / Windows (free-threading) / Build and test (arm64) (pull_request),Failing after 24m:

testexternalinspection.testcacheperthreadisolation fails in free-threading
ARM64 Windows CI (pre-existing).

Yashp002 · 2026-01-17T21:18:08Z

@encukou @StanFromIreland
Could you guide me if there are further changes needed with this PR?

encukou

I asked some more questions. Could you go through the unresolved comments here?

encukou · 2026-01-30T13:33:06Z

Doc/c-api/perfmaps.rst

+These unstable functions let you access and set perf map information
+about the current frame from C code.


This doesn't make sense to me. What is the connection to the current frame?

My bad, that text was completely out of place (and wrong). I'm deleting those lines entirely.

encukou · 2026-01-30T13:33:24Z

Doc/c-api/perfmaps.rst

+Note: Appends the content of the parent frame to the current one in perf maps.
+Just like in frameobject.h.


What function(s) is this note for? What is the connection to frameobject.h?

vstinner · 2026-02-02T11:46:39Z

Doc/c-api/perfmaps.rst

+   Open the ``/tmp/perf-$pid.map`` file and append the content of *parent_filename*
+   to it.
+
+   This function is only available on platforms that support perf maps (currently


This is not accurate, the function is "available" on all platforms. But it should only be used on Linux. On Windows, it does nothing (it's not implemented).

bedevere-app bot added docs Documentation in the Doc dir skip news labels Jan 6, 2026

github-project-automation bot added this to Docs PRs Jan 6, 2026

bedevere-app bot added the awaiting review label Jan 6, 2026

github-project-automation bot moved this to Todo in Docs PRs Jan 6, 2026

bedevere-app bot mentioned this pull request Jan 6, 2026

Document the entire C API #141004

Open

StanFromIreland requested changes Jan 6, 2026

View reviewed changes

bedevere-app bot added awaiting core review and removed awaiting review labels Jan 6, 2026

first commit perfmaps

9a85c56

Yashp002 force-pushed the doc-ceval-perf branch from 10b8fd7 to 9a85c56 Compare January 6, 2026 18:55

StanFromIreland reviewed Jan 6, 2026

View reviewed changes

fix 1 perfmaps

5e050f1

Yashp002 requested a review from StanFromIreland January 6, 2026 19:32

encukou mentioned this pull request Jan 7, 2026

gh-109587: Allow "precompiled" perf-trampolines to largely mitigate the cost of enabling perf-trampolines #109666

Merged

encukou reviewed Jan 8, 2026

View reviewed changes

ZeroIntensity reviewed Jan 8, 2026

View reviewed changes

fix 2 perfmaps

bd7eb99

Yashp002 mentioned this pull request Jan 8, 2026

gh-141004: Document unstable executable kind macros in pyframe.h #143490

Open

encukou reviewed Jan 30, 2026

View reviewed changes

Yashp002 added 3 commits January 31, 2026 23:22

perfmaps fix 3

e5a2111

Merge branch 'main' into doc-ceval-perf

a7a9e53

fix capi_ignored

85b98cf

vstinner reviewed Feb 2, 2026

View reviewed changes

perfmaps fix 4

5c89eea

		.. versionadded:: 3.12


		.. c:macro:: PyUnstable_EXECUTABLE_KIND_SKIP


		.. c:function:: int PyUnstable_CopyPerfMapFile(const char *parent_filename)

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


		.. c:function:: int PyUnstable_PerfTrampoline_CompileCode(PyCodeObject *code)

		Compile the given code object using the current perf trampoline.


		.. c:function:: int PyUnstable_PerfTrampoline_SetPersistAfterFork(int enable)

		Set whether the perf trampoline should persist after a fork.

		These unstable functions let you access and set perf map information
		about the current frame from C code.

		Note: Appends the content of the parent frame to the current one in perf maps.
		Just like in frameobject.h.

Uh oh!

Conversation

Yashp002 commented Jan 6, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ZeroIntensity left a comment

Choose a reason for hiding this comment

Uh oh!

Yashp002 commented Jan 8, 2026

Uh oh!

Yashp002 commented Jan 17, 2026

Uh oh!

encukou left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Yashp002 commented Jan 6, 2026 •

edited by github-actions bot

Loading