gh-141004: Document unstable perf map functions in ceval.h
#143492
Conversation
Doc/c-api/frame.rst
Outdated
| .. versionadded:: 3.12 | ||
| .. c:macro:: PyUnstable_EXECUTABLE_KIND_SKIP |
There was a problem hiding this comment.
You used the branch from the other PR, please remove these changes here.
There was a problem hiding this comment.
I'm so sorry yes, fixing rn.
There was a problem hiding this comment.
I hope it's not an issue if i force push a new branch over this one to fix my error?
There was a problem hiding this comment.
In general, avoid them, in this case I think it is fine to remove the changes.
Yashp002
force-pushed
the
doc-ceval-perf
branch
from
10b8fd7 to
9a85c56
Compare
| .. c:function:: int PyUnstable_CopyPerfMapFile(const char *parent_filename) | ||
| Open the ``/tmp/perf-$pid.map`` file and append the content of *parent_filename* |
There was a problem hiding this comment.
This should note what happens on Windows where this obviously won't work.
There was a problem hiding this comment.
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…”
There was a problem hiding this comment.
@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."
There was a problem hiding this comment.
@encukou or @StanFromIreland Could you verify this one too?
There was a problem hiding this comment.
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).
Doc/c-api/perfmaps.rst
Outdated
| 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. |
There was a problem hiding this comment.
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* |
There was a problem hiding this comment.
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).
| .. c:function:: int PyUnstable_PerfTrampoline_CompileCode(PyCodeObject *code) | ||
| Compile the given code object using the current perf trampoline. |
There was a problem hiding this comment.
What's the perf trampoline? How do you set the current one? What happens if there's no current trampoline?
| .. c:function:: int PyUnstable_PerfTrampoline_SetPersistAfterFork(int enable) | ||
| Set whether the perf trampoline should persist after a fork. |
There was a problem hiding this comment.
This isn't very clear to me; could you add/link more explanation about the behaviour on fork?
3 participants
gh-141004: Document unstable perf map functions in
ceval.hThis PR documents the
PyUnstable_CopyPerfMapFile,PyUnstable_PerfTrampoline_CompileCode, andPyUnstable_PerfTrampoline_SetPersistAfterForkfunctions inDoc/c-api/perfmaps.rst.📚 Documentation preview 📚: https://cpython-previews--143492.org.readthedocs.build/