gh-131253: free-threaded build support for pystats #137189

nascheme · 2025-07-28T22:50:09Z

Allow the --enable-pystats build option to be used with free-threading. For the free-threaded builds, the stats structure is allocated per-thread and then periodically merged into a per-interpter stats structure (on thread exit or when the reporting function is called).

Summary of changes:

Add pystats to the PyThreadState structure. This is a pointer to the PyStats structure if recording of stats is enabled. This is used for both the free-threaded and default builds.
For the free-threaded build, the _PyThreadStateImpl structure gains a pystats_struct member. This is allocated per-thread when recording of pystats is first enabled.
replace _Py_stats references with _PyStats_GET()
move pystats logic from Python/specialize.c into Python/pystats.c
move the pystats global state into the interpreter structure
add some free-threaded specific stat counters

Notes and potential issues:

The FTStats counts will need review. I wasn't sure about the naming or even how useful these might be. For mutex_sleeps, we need to determine what is the most useful thing to measure. I increment that count whenever we have to "spin" on a mutex.
The verbose code for print_* and merge_* is perhaps not ideal. I considered making this data driven instead. However, I think that actually would add complexity, not reduce it.
I plan on adding two levels of pystats recording: default and extended. The "default" level would be enabled by default (or at least could be) and would only include stats that are relatively cheap to record. The "extended" level would be like what the current --enable-pystats does (counting things like INCREF/DECREF, which is expensive).

Issue: Use pystats for free threading performance statistics #131253

Allow the --enable-pystats build option to be used with free-threading. For the free-threaded builds, the stats structure is allocated per-thread and then periodically merged into a global stats structure (on thread exit or when the reporting function is called). Summary of changes: * introduce _Py_tss_stats thread-local variable. This is set when stats are on, replacing the _Py_stats global that's used in the non-free-threaded build. * replace _Py_stats references with _PyStats_GET() * move pystats logic from Python/specialize.c into Python/pystats.c * add some free-threaded specific stat counters

colesbury

The management of the thread local variable seems complex. Can we keep the thread-local stats on PyThreadState and have _PyStats_GET() return something like _PyThreadState_GET()->stats? How much would the extra indirection slow down the stats build?

Include/cpython/pystats.h

nascheme · 2025-07-31T19:24:53Z

The management of the thread local variable seems complex. Can we keep the thread-local stats on PyThreadState and have _PyStats_GET() return something like _PyThreadState_GET()->stats? How much would the extra indirection slow down the stats build?

Yeah, it's maybe overly complex. I don't think there would be much performance difference since tstate is already used so heavily. Is there a problem with adding a pystats entry to the public PyThreadState structure?

colesbury · 2025-07-31T19:26:29Z

If you are considered about exposing it publicly, you can add to it _PyThreadStateImpl. Every PyThreadState* is actually a _PyThreadStateImpl and the extra fields are places after the publicly visible PyThreadState fields.

Need to do a merge before reporting (I lost that bit of code on a re-factor). Fix various issues with data races. When merging from all threads, we need to stop-the-world to avoid races. When toggling on or off, also need to stop-the-world. Remove the need for locking for _PyStats_Attach().

nascheme · 2025-07-31T22:41:30Z

I don't think there would be much performance difference since tstate is already used so heavily.

After some profiling, it seems that having the pystats pointer in tstate, rather than it's own thread-local adds about 5% extra overhead. Obviously that would depend on a lot of factors. However, given that the full pystats recording in very heavyweight (increments stat counts on incref/decref, for example), I think that's a totally acceptable performance cost in exchange for some simpler code.

Add pystats pointer to PyThreadState and use from there instead. This is slightly slower but shouldn't matter in practice. This simplifies the attach/detach logic as well.

Include/cpython/pystats.h

markshannon · 2025-10-09T08:30:40Z

Looks good in general. Moving the stats to its own file makes a lot of sense.

How have you tested this? We used to be able to use the Microsoft test runner to show the diff in stats, but that's not available any more.

Objects/object.c

nascheme · 2025-10-20T21:17:36Z

How have you tested this? We used to be able to use the Microsoft test runner to show the diff in stats, but that's not available any more.

I ran various scripts with pystats enabled, then compared the output (with and without this PR), ignoring differences in the counts.

Python/pystats.c

Add the _PyStats_InterpInit() function which will set pystats_enabled flag and allocate pystats_struct as required. We shouldn't be putting logic in _PyObject_InitState(). This also fixes a bug where interp->pystats_struct was allocated repeated rather than once per interpreter.

This is a bit more efficient, with the downside of a bit extra code. For _PyStats_Clear(), we don't need to do the merging operation. I think the code is a bit more clear this way.

sergey-miryanov · 2025-10-23T06:01:01Z

Python/pystats.c

+    if (interp->config._pystats) {
+        // start with pystats enabled, can be disabled via sys._stats_off()
+        // this needs to be set before the first tstate is created
+        interp->pystats_enabled = 1;


IIUC, we use PyMem_RawCalloc to allocate new interp memory. Then the default value of interp->pystats_enabled is 0, so if interp->config._pystats is false, we don't need to initialize it.

sergey-miryanov

LGTM

kumaraditya303 · 2025-10-23T07:55:33Z

Include/cpython/pystate.h

+static inline PyStats*
+_PyThreadState_GetStatsFast(void)
+{
+    if (_Py_tss_tstate == NULL) {


I think you should be able to use _PyThreadState_GetCurrent instead of accessing here

I don't want _PyThreadState_GetCurrent() because I want to inline the access to _Py_tss_tstate->pystats. The _PyStats_GET() function is used a lot from hot paths.

I could potentially use _PyThreadState_GET(). However, I don't see an easy way to make that work. The header that defines that inline function is not always included, e.g. for Programs/_freeze_module. Accessing _Py_tss_state directly is the simplest way I could find to do it.

Python/pystats.c

Need to allocate in stats_toggle_on_off() if the thread never had stats enabled yet. For zeroing, handle case that struct is not allocated. Remove bogus ts->_status.active check.

Lib/test/test_pystats.py

Co-authored-by: Kumar Aditya <kumaraditya@python.org>

Include/cpython/pystate.h

kumaraditya303 · 2025-10-30T10:53:19Z

Include/cpython/pystate.h

 PyAPI_FUNC(void) PyThreadState_LeaveTracing(PyThreadState *tstate);

+#ifdef Py_STATS
+#if defined(HAVE_THREAD_LOCAL) && !defined(Py_BUILD_CORE_MODULE)


With #140690, HAVE_THREAD_LOCAL check is not needed

I think it's still needed. In pycore_pystate.h we have:

#if defined(HAVE_THREAD_LOCAL) && !defined(Py_BUILD_CORE_MODULE) extern _Py_thread_local PyThreadState *_Py_tss_tstate; #endif

I could change the code to:

#if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)

But I don't think that's better.

Include/cpython/pystate.h

kumaraditya303 · 2025-10-30T10:54:27Z

Include/cpython/pystats.h

+// Export for most shared extensions
+PyAPI_FUNC(PyStats *) _PyStats_GetLocal(void);
+
+#if defined(HAVE_THREAD_LOCAL) && !defined(Py_BUILD_CORE_MODULE)


Co-authored-by: Kumar Aditya <kumaraditya@python.org>

bedevere-app bot mentioned this pull request Jul 28, 2025

Use pystats for free threading performance statistics #131253

Open

nascheme added the topic-free-threading label Jul 28, 2025

nascheme added 3 commits July 29, 2025 17:47

Make pystats global state be per-interpreter.

7dc9191

Add NEWS.

60454a2

Merge 'origin/main' into pythongh-131253-pystats-ft

df1c5d4

nascheme requested a review from colesbury July 30, 2025 19:17

colesbury reviewed Jul 31, 2025

View reviewed changes

Include/cpython/pystats.h Outdated Show resolved Hide resolved

nascheme added 2 commits August 6, 2025 16:08

Remove _Py_tss_stats thread local.

e77af2c

Add pystats pointer to PyThreadState and use from there instead. This is slightly slower but shouldn't matter in practice. This simplifies the attach/detach logic as well.

Merge 'origin/main' into pythongh-131253-pystats-ft

488f0be

nascheme force-pushed the gh-131253-pystats-ft branch from 3f58012 to 488f0be Compare August 6, 2025 23:12

nascheme added 2 commits August 7, 2025 14:50

Improve _Py_STATS_COND_EXPR macro.

a48c7f6

Improve comment for ts->pystats member.

612ea96

nascheme marked this pull request as ready for review August 8, 2025 00:03

nascheme requested review from a team, AA-Turner, ZeroIntensity, ammaraskar, ericsnowcurrently, erlend-aasland and markshannon as code owners August 8, 2025 00:03

bedevere-app bot added the awaiting core review label Aug 8, 2025

kumaraditya303 reviewed Aug 13, 2025

View reviewed changes

Include/cpython/pystats.h Show resolved Hide resolved

markshannon reviewed Oct 9, 2025

View reviewed changes

Objects/object.c Outdated Show resolved Hide resolved

markshannon self-requested a review October 22, 2025 16:52

markshannon approved these changes Oct 22, 2025

View reviewed changes

bedevere-app bot added awaiting merge and removed awaiting core review labels Oct 22, 2025

sergey-miryanov reviewed Oct 22, 2025

View reviewed changes

Python/pystats.c Show resolved Hide resolved

sergey-miryanov reviewed Oct 22, 2025

View reviewed changes

Python/pystats.c Outdated Show resolved Hide resolved

sergey-miryanov reviewed Oct 22, 2025

View reviewed changes

Python/pystats.c Show resolved Hide resolved

nascheme added 2 commits October 22, 2025 17:03

Split stats zeroing into separate functions.

a3cfb7e

This is a bit more efficient, with the downside of a bit extra code. For _PyStats_Clear(), we don't need to do the merging operation. I think the code is a bit more clear this way.

nascheme requested a review from emmatyping as a code owner October 23, 2025 00:23

Merge 'origin/main' into pythongh-131253-pystats-ft

724b086

sergey-miryanov reviewed Oct 23, 2025

View reviewed changes

sergey-miryanov approved these changes Oct 23, 2025

View reviewed changes

kumaraditya303 reviewed Oct 23, 2025

View reviewed changes

Python/pystats.c Outdated Show resolved Hide resolved

nascheme added 3 commits October 24, 2025 11:54

Fix a couple bugs related to stats allocation.

bef1bcb

Need to allocate in stats_toggle_on_off() if the thread never had stats enabled yet. For zeroing, handle case that struct is not allocated. Remove bogus ts->_status.active check.

Add unit test for pystats.

5034375

Merge 'origin/main' into pythongh-131253-pystats-ft

af9d886

kumaraditya303 reviewed Oct 28, 2025

View reviewed changes

Lib/test/test_pystats.py Outdated Show resolved Hide resolved

Typo fix for Lib/test/test_pystats.py

09011fe

Co-authored-by: Kumar Aditya <kumaraditya@python.org>

kumaraditya303 reviewed Oct 30, 2025

View reviewed changes

Include/cpython/pystate.h Outdated Show resolved Hide resolved

kumaraditya303 reviewed Oct 30, 2025

View reviewed changes

Include/cpython/pystate.h Outdated Show resolved Hide resolved

kumaraditya303 reviewed Oct 30, 2025

View reviewed changes

Include/cpython/pystate.h Show resolved Hide resolved

kumaraditya303 reviewed Oct 30, 2025

View reviewed changes

nascheme and others added 2 commits November 3, 2025 10:04

Typo fix for comment in Include/cpython/pystate.h

1e5db7a

Co-authored-by: Kumar Aditya <kumaraditya@python.org>

Code style tweaks.

873d915

nascheme merged commit c98c5b3 into python:main Nov 3, 2025
52 checks passed

bedevere-app bot removed the awaiting merge label Nov 3, 2025

Uh oh!

gh-131253: free-threaded build support for pystats #137189

gh-131253: free-threaded build support for pystats #137189

Uh oh!

Conversation

nascheme commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

colesbury left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nascheme commented Jul 31, 2025

Uh oh!

colesbury commented Jul 31, 2025

Uh oh!

nascheme commented Jul 31, 2025

Uh oh!

Uh oh!

markshannon commented Oct 9, 2025

Uh oh!

Uh oh!

nascheme commented Oct 20, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

sergey-miryanov Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

sergey-miryanov left a comment

Choose a reason for hiding this comment

Uh oh!

kumaraditya303 Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

nascheme Oct 24, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kumaraditya303 Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

nascheme Nov 3, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

kumaraditya303 Oct 30, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

nascheme commented Jul 28, 2025 •

edited

Loading