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

 .. 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

+
+.. 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

+ 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

+
+.. 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).

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

+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

+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

+ 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).

github-actions · 2026-05-04T12:32:49Z

This PR is stale because it has been open for 30 days with no activity.

read-the-docs-community · 2026-06-03T12:31:57Z

Documentation build overview

📚 cpython-previews | 🛠️ Build #32971943 | 📁 Comparing ba3e3cf against main (5553e00)

🔍 Preview build

2 files changed

±c-api/perfmaps.html
±whatsnew/changelog.html

ZeroIntensity

I don't see any more blocking issues here -- let's get these documented!

If anyone disagrees with anything here, or otherwise want to make some change to the test, feel free to send a follow-up and tag me on it.

miss-islington-app · 2026-06-03T12:36:30Z

Thanks @Yashp002 for the PR, and @ZeroIntensity for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14, 3.15.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

miss-islington-app · 2026-06-03T12:36:42Z

Sorry, @Yashp002 and @ZeroIntensity, I could not cleanly backport this to 3.14 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 6453065db9ff31e3f737240030f8311d2b087851 3.14

bedevere-app · 2026-06-03T12:36:46Z

GH-150849 is a backport of this pull request to the 3.15 branch.

miss-islington-app · 2026-06-03T12:36:48Z

Sorry, @Yashp002 and @ZeroIntensity, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 6453065db9ff31e3f737240030f8311d2b087851 3.13

…H-143492) (GH-150849) gh-141004: Document unstable perf map functions in `ceval.h` (GH-143492) (cherry picked from commit 6453065) Co-authored-by: Yashraj <yashrajpala8@gmail.com>

…ythonGH-143492)

serhiy-storchaka · 2026-07-15T08:15:29Z

Please don't forget about backports.

bedevere-app · 2026-07-18T14:57:40Z

GH-153994 is a backport of this pull request to the 3.14 branch.

bedevere-app · 2026-07-18T14:59:35Z

GH-153996 is a backport of this pull request to the 3.13 branch.

…H-143492) (GH-153996) (cherry picked from commit 6453065) Co-authored-by: Yashraj <yashrajpala8@gmail.com>

…H-143492) (GH-153994) (cherry picked from commit 6453065) Co-authored-by: Yashraj <yashrajpala8@gmail.com>

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

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

bedevere-appBot added the awaiting review label Jan 6, 2026

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

bedevere-appBot mentioned this pull request Jan 6, 2026
Document the entire C API #141004
Open

StanFromIreland requested changes Jan 6, 2026
View reviewed changes

bedevere-appBot 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 9a85c56Compare 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
Merged

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

github-actionsBot added the stale Stale PR or inactive for long period of time. label May 4, 2026

Merge branch 'main' into doc-ceval-perf
ba3e3cf

ZeroIntensity approved these changes Jun 3, 2026
View reviewed changes

bedevere-appBot added awaiting merge and removed awaiting core review labels Jun 3, 2026

ZeroIntensity enabled auto-merge (squash) June 3, 2026 12:33

ZeroIntensity added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes needs backport to 3.15 pre-release feature fixes, bugs and security fixes and removed stale Stale PR or inactive for long period of time. labels Jun 3, 2026

ZeroIntensity merged commit 6453065 into python:mainJun 3, 2026
51 checks passed

github-project-automationBot moved this from Todo to Done in Docs PRs Jun 3, 2026

bedevere-appBot removed the awaiting merge label Jun 3, 2026

miss-islington-appBot assigned ZeroIntensity Jun 3, 2026

bedevere-appBot removed the needs backport to 3.15 pre-release feature fixes, bugs and security fixes label Jun 3, 2026

philthompson10 pushed a commit to philthompson10/cpython that referenced this pull request Jun 17, 2026
pythongh-141004: Document unstable perf map functions inceval.h(p…
c605ffe
…ythonGH-143492)

bedevere-appBot removed the needs backport to 3.14 bugs and security fixes label Jul 18, 2026

bedevere-appBot removed the needs backport to 3.13 bugs and security fixes label Jul 18, 2026

ZeroIntensity added a commit that referenced this pull request Jul 18, 2026
[3.13]gh-141004: Document unstable perf map functions inceval.h(G…
78b6bb9
…H-143492) (GH-153996) (cherry picked from commit 6453065) Co-authored-by: Yashraj <yashrajpala8@gmail.com>

ZeroIntensity added a commit that referenced this pull request Jul 18, 2026
[3.14]gh-141004: Document unstable perf map functions inceval.h(G…
27c5953
…H-143492) (GH-153994) (cherry picked from commit 6453065) Co-authored-by: Yashraj <yashrajpala8@gmail.com>

		.. 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

		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!

Uh oh!

Conversation

Yashp002 commented Jan 6, 2026• edited by github-actions BotLoading 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!

Uh oh!

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!

github-actionsBot commented May 4, 2026

Uh oh!

read-the-docs-communityBot commented Jun 3, 2026

Documentation build overview

Uh oh!

ZeroIntensity left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

miss-islington-appBot commented Jun 3, 2026

Uh oh!

miss-islington-appBot commented Jun 3, 2026

Uh oh!

bedevere-appBot commented Jun 3, 2026

Uh oh!

miss-islington-appBot commented Jun 3, 2026

Uh oh!

serhiy-storchaka commented Jul 15, 2026

Uh oh!

bedevere-appBot commented Jul 18, 2026

Uh oh!

bedevere-appBot commented Jul 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Yashp002 commented Jan 6, 2026•
edited by github-actions Bot
Loading