gh-135953: Add GIL contention markers to sampling profiler Gecko format

This commit enhances the Gecko format reporter in the sampling profiler
to include markers for GIL acquisition events. The implementation adds:

- GIL contention tracking in pystate and ceval_gil
- New marker types in the Gecko collector for GIL wait events
- External inspection support for reading GIL state
- Sample collection of GIL acquisition times and thread states
- Comprehensive tests for marker export functionality

The markers provide visibility into GIL contention patterns, showing
when threads are waiting to acquire the GIL and how long they wait.

Author: pablogsal

Include/cpython/pystate.h

@@ -113,6 +113,11 @@ struct _ts {
     /* Currently holds the GIL. Must be its own field to avoid data races */
     int holds_gil;
 
+#ifndef Py_GIL_DISABLED
+    /* Currently requesting the GIL (waiting for it). Must be its own field to avoid data races */
+    int gil_requested;
+#endif
+
     int _whence;
 
     /* Thread state (_Py_THREAD_ATTACHED, _Py_THREAD_DETACHED, _Py_THREAD_SUSPENDED).

Include/internal/pycore_debug_offsets.h

@@ -55,12 +55,14 @@ extern "C" {
 # define _Py_Debug_code_object_co_tlbc offsetof(PyCodeObject, co_tlbc)
 # define _Py_Debug_interpreter_frame_tlbc_index offsetof(_PyInterpreterFrame, tlbc_index)
 # define _Py_Debug_interpreter_state_tlbc_generation offsetof(PyInterpreterState, tlbc_indices.tlbc_generation)
+# define _Py_Debug_thread_state_gil_requested 0
 #else
 # define _Py_Debug_gilruntimestate_enabled 0
 # define _Py_Debug_Free_Threaded 0
 # define _Py_Debug_code_object_co_tlbc 0
 # define _Py_Debug_interpreter_frame_tlbc_index 0
 # define _Py_Debug_interpreter_state_tlbc_generation 0
+# define _Py_Debug_thread_state_gil_requested offsetof(PyThreadState, gil_requested)
 #endif
 
 
@@ -106,6 +108,8 @@ typedef struct _Py_DebugOffsets {
         uint64_t native_thread_id;
         uint64_t datastack_chunk;
         uint64_t status;
+        uint64_t holds_gil;
+        uint64_t gil_requested;
     } thread_state;
 
     // InterpreterFrame offset;
@@ -273,6 +277,8 @@ typedef struct _Py_DebugOffsets {
         .native_thread_id = offsetof(PyThreadState, native_thread_id), \
         .datastack_chunk = offsetof(PyThreadState, datastack_chunk), \
         .status = offsetof(PyThreadState, _status), \
+        .holds_gil = offsetof(PyThreadState, holds_gil), \
+        .gil_requested = _Py_Debug_thread_state_gil_requested, \
     }, \
     .interpreter_frame = { \
         .size = sizeof(_PyInterpreterFrame), \

Lib/profiling/sampling/collector.py

@@ -1,17 +1,13 @@
 from abc import ABC, abstractmethod
 
-# Enums are slow
-THREAD_STATE_RUNNING = 0
-THREAD_STATE_IDLE = 1
-THREAD_STATE_GIL_WAIT = 2
-THREAD_STATE_UNKNOWN = 3
-
-STATUS = {
-    THREAD_STATE_RUNNING: "running",
-    THREAD_STATE_IDLE: "idle",
-    THREAD_STATE_GIL_WAIT: "gil_wait",
-    THREAD_STATE_UNKNOWN: "unknown",
-}
+# Thread status flags
+try:
+    from _remote_debugging import THREAD_STATUS_HAS_GIL, THREAD_STATUS_ON_CPU, THREAD_STATUS_UNKNOWN
+except ImportError:
+    # Fallback for tests or when module is not available
+    THREAD_STATUS_HAS_GIL = (1 << 0)
+    THREAD_STATUS_ON_CPU = (1 << 1)
+    THREAD_STATUS_UNKNOWN = (1 << 2)
 
 class Collector(ABC):
     @abstractmethod
@@ -26,8 +22,14 @@ def _iter_all_frames(self, stack_frames, skip_idle=False):
         """Iterate over all frame stacks from all interpreters and threads."""
         for interpreter_info in stack_frames:
             for thread_info in interpreter_info.threads:
-                if skip_idle and thread_info.status != THREAD_STATE_RUNNING:
-                    continue
+                # skip_idle now means: skip if thread is not actively running
+                # A thread is "active" if it has the GIL OR is on CPU
+                if skip_idle:
+                    status_flags = thread_info.status
+                    has_gil = bool(status_flags & THREAD_STATUS_HAS_GIL)
+                    on_cpu = bool(status_flags & THREAD_STATUS_ON_CPU)
+                    if not (has_gil or on_cpu):
+                        continue
                 frames = thread_info.frame_info
                 if frames:
                     yield frames, thread_info.thread_id