gh-117139: A StackRef Debugging Mode

.github/workflows/build.yml

@@ -241,6 +241,19 @@ jobs:
  # Cirrus used for upstream, macos-14 for forks.
  os-matrix: '["ghcr.io/cirruslabs/macos-runner:sonoma", "macos-14"]'
 
+ build_macos_free_threading_with_stackref_debug:
+ name: 'macOS (free-threading) (StackRef Debug)'
+ needs: check_source
+ if: needs.check_source.outputs.run_tests == 'true'
+ uses: ./.github/workflows/reusable-macos.yml
+ with:
+ config_hash: ${{needs.check_source.outputs.config_hash }}
+ free-threading: true
+ stackref-debug: true
+ # Cirrus and macos-14 are M1.
+ # Cirrus used for upstream, macos-14 for forks.
+ os-matrix: '["ghcr.io/cirruslabs/macos-runner:sonoma", "macos-14"]'
+
  build_ubuntu:
  name: 'Ubuntu'
  needs: check_source
@@ -577,6 +590,7 @@ jobs:
  - check_generated_files
  - build_macos
  - build_macos_free_threading
+ - build_macos_free_threading_with_stackref_debug
  - build_ubuntu
  - build_ubuntu_free_threading
  - build_ubuntu_ssltests

.github/workflows/reusable-macos.yml

@@ -8,6 +8,10 @@ on:
  required: false
  type: boolean
  default: false
+ stackref-debug:
+ required: false
+ type: boolean
+ default: false
  os-matrix:
  required: false
  type: string
@@ -54,11 +58,14 @@ jobs:
  --config-cache \
  --with-pydebug \
  ${{inputs.free-threading && '--disable-gil' || ''}} \
+ ${{inputs.stackref-debug && '--with-pystackrefdebug' || ''}} \
  --prefix=/opt/python-dev \
  --with-openssl="$(brew --prefix [email protected])"
  - name: Build CPython
  run: make -j8
  - name: Display build info
  run: make pythoninfo
  - name: Tests
- run: make test
+ # Stackref debug is 3.5x slower than normal CPython,
+ # so we only run it on a restricted subset of tests.
+ run: ${{inputs.stackref-debug && './python.exe -m test test_typing' || 'make test'}}

Include/internal/pycore_interp.h

@@ -275,6 +275,10 @@ struct _is{
  /* the initial PyInterpreterState.threads.head */
  _PyThreadStateImpl _initial_thread;
  Py_ssize_t _interactive_src_count;
+
+#if defined(Py_STACKREF_DEBUG) && defined(Py_GIL_DISABLED)
+ struct _Py_stackref_state stackref_state;
+#endif
 };
 
 

Include/internal/pycore_stackref.h

@@ -9,6 +9,7 @@ extern "C"{
 #endif
 
 #include "pycore_object_deferred.h"
+#include "pycore_hashtable.h"
 
 #include <stddef.h>
 
@@ -52,42 +53,93 @@ typedef union _PyStackRef{
  uintptr_t bits;
 } _PyStackRef;
 
+struct _Py_stackref_state{
+ PyMutex lock;
+ _Py_hashtable_t *entries;
+ size_t next_ref;
+};
+
+typedef enum _PyStackRef_OpKind{
+ BORROW,
+ STEAL,
+ NEW,
+} _PyStackRef_OpKind;
+
+PyAPI_FUNC(PyObject *)_Py_stackref_to_object_transition(_PyStackRef stackref, _PyStackRef_OpKind op);
+PyAPI_FUNC(_PyStackRef) _Py_object_to_stackref_transition(PyObject *obj, char tag, _PyStackRef_OpKind op);
+PyAPI_FUNC(int) _PyStackRef_IsLive(_PyStackRef stackref);
+PyAPI_FUNC(void) _PyStackRef_Close(_PyStackRef stackref);
+PyAPI_FUNC(_PyStackRef) _PyStackRef_Dup(_PyStackRef stackref);
 
 #define Py_TAG_DEFERRED (1)
 
 #define Py_TAG_PTR (0)
 #define Py_TAG_BITS (1)
 
+#define RESERVED_BITS 1
+
 #ifdef Py_GIL_DISABLED
  static const _PyStackRef PyStackRef_NULL ={.bits = 0 | Py_TAG_DEFERRED};
 #else
  static const _PyStackRef PyStackRef_NULL ={.bits = 0 };
 #endif
 
-#define PyStackRef_IsNull(stackref) ((stackref).bits == PyStackRef_NULL.bits)
-
 
 #ifdef Py_GIL_DISABLED
-# define PyStackRef_True ((_PyStackRef){.bits = ((uintptr_t)&_Py_TrueStruct) | Py_TAG_DEFERRED })
+# ifdef Py_STACKREF_DEBUG
+ // From pycore_init_stackrefs in pylifecycle.c
+ static const _PyStackRef PyStackRef_True ={.bits = 1 << RESERVED_BITS };
+# else
+# define PyStackRef_True ((_PyStackRef){.bits = ((uintptr_t)&_Py_TrueStruct) | Py_TAG_DEFERRED })
+# endif
 #else
 # define PyStackRef_True ((_PyStackRef){.bits = ((uintptr_t)&_Py_TrueStruct) })
 #endif
 
 #ifdef Py_GIL_DISABLED
-# define PyStackRef_False ((_PyStackRef){.bits = ((uintptr_t)&_Py_FalseStruct) | Py_TAG_DEFERRED })
+# ifdef Py_STACKREF_DEBUG
+ // From pycore_init_stackrefs in pylifecycle.c
+ static const _PyStackRef PyStackRef_False ={.bits = 2 << RESERVED_BITS };
+# else
+# define PyStackRef_False ((_PyStackRef){.bits = ((uintptr_t)&_Py_FalseStruct) | Py_TAG_DEFERRED })
+# endif
 #else
 # define PyStackRef_False ((_PyStackRef){.bits = ((uintptr_t)&_Py_FalseStruct) })
 #endif
 
 #ifdef Py_GIL_DISABLED
+# ifdef Py_STACKREF_DEBUG
+ // From pycore_init_stackrefs in pylifecycle.c
+ static const _PyStackRef PyStackRef_None ={.bits = 3 << RESERVED_BITS };
+# else
 # define PyStackRef_None ((_PyStackRef){.bits = ((uintptr_t)&_Py_NoneStruct) | Py_TAG_DEFERRED })
+# endif
 #else
 # define PyStackRef_None ((_PyStackRef){.bits = ((uintptr_t)&_Py_NoneStruct) })
 #endif
 
 // Note: the following are all macros because MSVC (Windows) has trouble inlining them.
 
-#define PyStackRef_Is(a, b) ((a).bits == (b).bits)
+#ifdef Py_GIL_DISABLED
+static inline int
+PyStackRef_Is(_PyStackRef a, _PyStackRef b){
+# ifdef Py_STACKREF_DEBUG
+ // Note: stackrefs are unique. So even immortal objects will produce different stackrefs.
+ return _Py_stackref_to_object_transition(a, BORROW) == _Py_stackref_to_object_transition(b, BORROW);
+# else
+ return a.bits == b.bits;
+# endif
+}
+#else
+# define PyStackRef_Is(a, b) ((a).bits == (b).bits)
+#endif
+
+static inline int
+PyStackRef_IsNull(_PyStackRef stackref)
+{
+ return PyStackRef_Is(stackref, PyStackRef_NULL);
+}
+
 
 #define PyStackRef_IsDeferred(ref) (((ref).bits & Py_TAG_BITS) == Py_TAG_DEFERRED)
 
@@ -97,8 +149,12 @@ typedef union _PyStackRef{
 static inline PyObject *
 PyStackRef_AsPyObjectBorrow(_PyStackRef stackref)
 {
+# ifdef Py_STACKREF_DEBUG
+ return _Py_stackref_to_object_transition(stackref, BORROW);
+# else
  PyObject *cleared = ((PyObject *)((stackref).bits & (~Py_TAG_BITS)));
  return cleared;
+# endif
 }
 #else
 # define PyStackRef_AsPyObjectBorrow(stackref) ((PyObject *)(stackref).bits)
@@ -110,10 +166,14 @@ PyStackRef_AsPyObjectBorrow(_PyStackRef stackref)
 static inline PyObject *
 PyStackRef_AsPyObjectSteal(_PyStackRef stackref)
 {
+# ifdef Py_STACKREF_DEBUG
+ return _Py_stackref_to_object_transition(stackref, STEAL);
+# else
  if (!PyStackRef_IsNull(stackref) && PyStackRef_IsDeferred(stackref)){
  return Py_NewRef(PyStackRef_AsPyObjectBorrow(stackref));
  }
  return PyStackRef_AsPyObjectBorrow(stackref);
+# endif
 }
 #else
 # define PyStackRef_AsPyObjectSteal(stackref) PyStackRef_AsPyObjectBorrow(stackref)
@@ -133,7 +193,11 @@ _PyStackRef_FromPyObjectSteal(PyObject *obj)
  // Make sure we don't take an already tagged value.
  assert(((uintptr_t)obj & Py_TAG_BITS) == 0);
  int tag = (obj == NULL || _Py_IsImmortal(obj)) ? (Py_TAG_DEFERRED) : Py_TAG_PTR;
+# ifdef Py_STACKREF_DEBUG
+ return _Py_object_to_stackref_transition(obj, tag, STEAL);
+# else
  return ((_PyStackRef){.bits = ((uintptr_t)(obj)) | tag});
+# endif
 }
 # define PyStackRef_FromPyObjectSteal(obj) _PyStackRef_FromPyObjectSteal(_PyObject_CAST(obj))
 #else
@@ -151,10 +215,18 @@ PyStackRef_FromPyObjectNew(PyObject *obj)
  assert(obj != NULL);
  // TODO (gh-117139): Add deferred objects later.
  if (_Py_IsImmortal(obj)){
+# ifdef Py_STACKREF_DEBUG
+ return _Py_object_to_stackref_transition(obj, Py_TAG_DEFERRED, NEW);
+# else
  return (_PyStackRef){.bits = (uintptr_t)obj | Py_TAG_DEFERRED };
+# endif
  }
  else{
+# ifdef Py_STACKREF_DEBUG
+ return _Py_object_to_stackref_transition(Py_NewRef(obj), Py_TAG_PTR, NEW);
+# else
  return (_PyStackRef){.bits = (uintptr_t)(Py_NewRef(obj)) | Py_TAG_PTR };
+# endif
  }
 }
 # define PyStackRef_FromPyObjectNew(obj) PyStackRef_FromPyObjectNew(_PyObject_CAST(obj))
@@ -171,7 +243,11 @@ PyStackRef_FromPyObjectImmortal(PyObject *obj)
  assert(((uintptr_t)obj & Py_TAG_BITS) == 0);
  assert(obj != NULL);
  assert(_Py_IsImmortal(obj));
+# ifdef Py_STACKREF_DEBUG
+ return _Py_object_to_stackref_transition(obj, Py_TAG_DEFERRED, NEW);
+# else
  return (_PyStackRef){.bits = (uintptr_t)obj | Py_TAG_DEFERRED };
+# endif
 }
 # define PyStackRef_FromPyObjectImmortal(obj) PyStackRef_FromPyObjectImmortal(_PyObject_CAST(obj))
 #else
@@ -199,6 +275,9 @@ PyStackRef_CLOSE(_PyStackRef stackref)
  return;
  }
  Py_DECREF(PyStackRef_AsPyObjectBorrow(stackref));
+# ifdef Py_STACKREF_DEBUG
+ _PyStackRef_Close(stackref);
+# endif
 }
 #else
 # define PyStackRef_CLOSE(stackref) Py_DECREF(PyStackRef_AsPyObjectBorrow(stackref));
@@ -217,6 +296,9 @@ PyStackRef_CLOSE(_PyStackRef stackref)
 static inline _PyStackRef
 PyStackRef_DUP(_PyStackRef stackref)
 {
+# ifdef Py_STACKREF_DEBUG
+ stackref = _PyStackRef_Dup(stackref);
+# endif
  if (PyStackRef_IsDeferred(stackref)){
  assert(PyStackRef_IsNull(stackref) ||
  _Py_IsImmortal(PyStackRef_AsPyObjectBorrow(stackref)));

Makefile.pre.in

@@ -474,6 +474,7 @@ PYTHON_OBJS= \
  Python/qsbr.o \
  Python/bootstrap_hash.o \
  Python/specialize.o \
+ Python/stackref.o \
  Python/structmember.o \
  Python/symtable.o \
  Python/sysmodule.o \

Misc/NEWS.d/next/Build/2024-06-29-00-02-42.gh-issue-117139.-lKXPB.rst

@@ -0,0 +1,4 @@
+Added a new ``--with-pystackrefs`` configure build option for CPython. This
+option is fully experimental and may be modified or removed without prior
+notice. Enabling the option turns on internal handle-like debugging for
+CPython's main interpreter loop.

Python/ceval.c

@@ -726,6 +726,18 @@ _PyObjectArray_Free(PyObject **array, PyObject **scratch)
  }
 }
 
+#if Py_STACKREF_DEBUG
+static int
+_PyEval_StackIsAllLive(_PyStackRef *stack_base, _PyStackRef *stack_pointer)
+{
+ while (stack_pointer > stack_base){
+ assert(_PyStackRef_IsLive(stack_pointer[-1]));
+ stack_pointer--;
+ }
+ return 1;
+}
+#endif
+
 /* _PyEval_EvalFrameDefault() is a *big* function,
  * so consume 3 units of C stack */
 #define PY_EVAL_C_STACK_UNITS 2

Python/ceval_macros.h

@@ -86,6 +86,17 @@
 #define PRE_DISPATCH_GOTO() ((void)0)
 #endif
 
+#ifdef Py_STACKREF_DEBUG
+#define STACKREF_CHECK() \
+ do{\
+ if (frame->f_executable && PyCode_Check(frame->f_executable)){\
+ _PyEval_StackIsAllLive(_PyFrame_Stackbase(frame), stack_pointer); \
+ }; \
+ } while (0);
+#else
+#define STACKREF_CHECK() ((void)(0))
+#endif
+
 #if LLTRACE
 #define LLTRACE_RESUME_FRAME() \
 do{\
@@ -110,13 +121,15 @@ do{\
 {\
  NEXTOPARG(); \
  PRE_DISPATCH_GOTO(); \
+ STACKREF_CHECK(); \
  DISPATCH_GOTO(); \
  }
 
 #define DISPATCH_SAME_OPARG() \
 {\
  opcode = next_instr->op.code; \
- PRE_DISPATCH_GOTO(); \
+ PRE_DISPATCH_GOTO(); \
+ STACKREF_CHECK(); \
  DISPATCH_GOTO(); \
  }
 

Python/pylifecycle.c

@@ -837,6 +837,35 @@ pycore_init_builtins(PyThreadState *tstate)
  return _PyStatus_ERR("can't initialize builtins module");
 }
 
+#if defined(Py_STACKREF_DEBUG) && defined(Py_GIL_DISABLED)
+static PyStatus
+pycore_init_stackrefs(PyInterpreterState *interp)
+{
+ _Py_hashtable_allocator_t alloc ={
+ .malloc = PyMem_Malloc,
+ .free = PyMem_Free,
+ };
+ interp->stackref_state.entries = _Py_hashtable_new_full(
+ _Py_hashtable_hash_ptr,
+ _Py_hashtable_compare_direct,
+ NULL,
+ NULL,
+ &alloc
+ );
+ if (interp->stackref_state.entries == NULL){
+ goto error;
+ }
+ interp->stackref_state.next_ref = 1;
+ // Reserve True, False, None
+ _Py_object_to_stackref_transition(Py_True, Py_TAG_DEFERRED, STEAL);
+ _Py_object_to_stackref_transition(Py_False, Py_TAG_DEFERRED, STEAL);
+ _Py_object_to_stackref_transition(Py_None, Py_TAG_DEFERRED, STEAL);
+ return _PyStatus_OK();
+
+error:
+ return _PyStatus_ERR("can't initialize stackrefs to pyobject mapping");
+}
+#endif
 
 static PyStatus
 pycore_interp_init(PyThreadState *tstate)
@@ -845,6 +874,13 @@ pycore_interp_init(PyThreadState *tstate)
  PyStatus status;
  PyObject *sysmod = NULL;
 
+#if defined(Py_STACKREF_DEBUG) && defined(Py_GIL_DISABLED)
+ status = pycore_init_stackrefs(interp);
+ if (_PyStatus_EXCEPTION(status)){
+ return status;
+ }
+#endif
+
  // Create singletons before the first PyType_Ready() call, since
  // PyType_Ready() uses singletons like the Unicode empty string (tp_doc)
  // and the empty tuple singletons (tp_bases).

Python/pystate.c

@@ -903,6 +903,10 @@ interpreter_clear(PyInterpreterState *interp, PyThreadState *tstate)
  interp->code_watchers[i] = NULL;
  }
  interp->active_code_watchers = 0;
+
+#if defined(Py_STACKREF_DEBUG) && defined(Py_GIL_DISABLED)
+ PyMem_Free(interp->stackref_state.entries);
+#endif
  // XXX Once we have one allocator per interpreter (i.e.
  // per-interpreter GC) we must ensure that all of the interpreter's
  // objects have been cleaned up at the point.