diff --git a/Doc/c-api/frame.rst b/Doc/c-api/frame.rst index fb17cf7f1da6b2..97c2bdd7db6166 100644 --- a/Doc/c-api/frame.rst +++ b/Doc/c-api/frame.rst @@ -250,3 +250,63 @@ Unless using :pep:`523`, you will not need this. .. versionadded:: 3.12 +.. c:type:: PyUnstable_ExecutableKinds + + An array of executable kinds (executor types) for frames, used for internal + debugging and tracing. + + Tools like debuggers and profilers can use this to identify the type of execution + context associated with a frame (For example: to filter out internal frames). + The entries are indexed by the following constants: + + .. list-table:: + :header-rows: 1 + :widths: auto + + * - Constant + - Description + * - .. c:macro:: PyUnstable_EXECUTABLE_KIND_SKIP + - The frame is internal (For example: inlined) and should be skipped by tools. + * - .. c:macro:: PyUnstable_EXECUTABLE_KIND_PY_FUNCTION + - The frame corresponds to a standard Python function. + + Example usage: + + .. code-block:: c + + // Check if a frame should be skipped + if (kind == PyUnstable_EXECUTABLE_KIND_SKIP) { + // This is an internal frame (like a Tier 2 optimizer frame) + // Tools should ignore it. + continue; + } + + .. versionadded:: 3.13 + + +.. c:macro:: PyUnstable_EXECUTABLE_KIND_PY_FUNCTION + + Index for the "Python function" kind in ``PyUnstable_ExecutableKinds``. + + .. versionadded:: 3.13 + + +.. c:macro:: PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION + + Index for the "built-in function" kind in ``PyUnstable_ExecutableKinds``. + + .. versionadded:: 3.13 + + +.. c:macro:: PyUnstable_EXECUTABLE_KIND_METHOD_DESCRIPTOR + + Index for the "method descriptor" kind in ``PyUnstable_ExecutableKinds``. + + .. versionadded:: 3.13 + + +.. c:macro:: PyUnstable_EXECUTABLE_KINDS + + The number of entries in ``PyUnstable_ExecutableKinds``. + + .. versionadded:: 3.13 diff --git a/Tools/check-c-api-docs/ignored_c_api.txt b/Tools/check-c-api-docs/ignored_c_api.txt index e0b2670808c79c..97a411d5067fbc 100644 --- a/Tools/check-c-api-docs/ignored_c_api.txt +++ b/Tools/check-c-api-docs/ignored_c_api.txt @@ -75,12 +75,6 @@ Py_UniversalNewlineFgets PyUnstable_CopyPerfMapFile PyUnstable_PerfTrampoline_CompileCode PyUnstable_PerfTrampoline_SetPersistAfterFork -# cpython/pyframe.h -PyUnstable_EXECUTABLE_KINDS -PyUnstable_EXECUTABLE_KIND_BUILTIN_FUNCTION -PyUnstable_EXECUTABLE_KIND_METHOD_DESCRIPTOR -PyUnstable_EXECUTABLE_KIND_PY_FUNCTION -PyUnstable_EXECUTABLE_KIND_SKIP # cpython/pylifecycle.h Py_FrozenMain # pythonrun.h