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

bedevere-app

Yashp002 commented
Jan 6, 2026
•

edited by github-actions Bot

Loading

		.. versionadded:: 3.12


		.. c:macro:: PyUnstable_EXECUTABLE_KIND_SKIP

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm so sorry yes, fixing rn.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


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

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

		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.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


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

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment on lines +53 to +54

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment on lines +56 to +57

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

		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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

philthompson10 pushed a commit to philthompson10/cpython that referenced this pull request

Jun 17, 2026

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

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Yashp002 commented
Jan 6, 2026
•

edited by github-actions Bot

Loading