GH-146527: Add get_gc_stats function to _remote_debugging

[sergey-miryanov]

This PR implements second part of the issue. Instead of adding a new module or extending the gc module we add new function to the _remote_debugging module as it is a best place for this.

• Issue: Add a module for monitoring GC statistics #146527

[sergey-miryanov]

I'm not sure about news entry too.

[sergey-miryanov]

@pablogsal Could you please take a look?

[pablogsal]

Thanks a lot for the great work on this @sergey-miryanov! I pushed a set of follow-up commits on top because we are getting close to beta freeze and I wanted to make sure this lands in a solid shape.

The follow-ups validate the remote GC stats offset and reject incompatible remote layoutsinstead of accepting short reads, reject a NULL remote GC stats pointer, record timestamps in the free-threaded GC path, and document why ts_stop is published last. I also moved the non-trivial GC stats implementation out of the header into gc_stats.c and updated the POSIX and Windows build files for that split. The API now returns _remote_debugging.GCStatsInfo structseq objects instead of dictionaries, matching the rest of _remote_debugging, and the docs/Clinic text now describes the fields and errors properly. I dropped heap_size from the exposed docs since it is not actually exposed by the current stats layout.

On the test side, I renamed the test file to test_gc_stats.py, added timestamp and field coverage, updated the assertions for GCStatsInfo, and changed the workload to allocate tracked self-referential containers so the candidate counts advance deterministically.

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #32509414 | 📁 Comparing 6e2c401 against main (c7b7ca2)

🔍 Preview build

4 files changed

±contents.html
±c-api/perfmaps.html
±whatsnew/3.15.html
±whatsnew/changelog.html

[pablogsal]

LGTM

Thanks for this @sergey-miryanov this was such a cool idea!

[sergey-miryanov]

Thanks so much, @pablogsal! You did excellent work shaping this into its final form!