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

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/

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.

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

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

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

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

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

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

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

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.

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

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

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

Documentation build overview

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

🔍 Preview build

2 files changed
± c-api/perfmaps.html
± whatsnew/changelog.html

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.

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!

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

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

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)

Please don't forget about backports.

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

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

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-actions Bot 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-app Bot 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:main Jun 3, 2026
51 checks passed

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

bedevere-app Bot removed the awaiting merge label Jun 3, 2026

miss-islington-app Bot assigned ZeroIntensity Jun 3, 2026

bedevere-app Bot 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 in ceval.h (p…

c605ffe

…ythonGH-143492)

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

bedevere-app Bot 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 in ceval.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 in ceval.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

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

		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.

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

Uh oh!

Uh oh!

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

gh-141004: Document unstable perf map functions in ceval.h#143492ZeroIntensity merged 8 commits intopython:mainpython/cpython:mainfrom Yashp002:doc-ceval-perfYashp002/cpython:doc-ceval-perfCopy head branch name to clipboard

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!

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-actions Bot commented May 4, 2026

Uh oh!

read-the-docs-community Bot 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-app Bot commented Jun 3, 2026

Uh oh!

miss-islington-app Bot commented Jun 3, 2026

Uh oh!

bedevere-app Bot commented Jun 3, 2026

Uh oh!

miss-islington-app Bot commented Jun 3, 2026

Uh oh!

serhiy-storchaka commented Jul 15, 2026

Uh oh!

bedevere-app Bot commented Jul 18, 2026

Uh oh!

bedevere-app Bot commented Jul 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

gh-141004: Document unstable perf map functions in ceval.h#143492
ZeroIntensity merged 8 commits into
python:mainfrom
Yashp002:doc-ceval-perf

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