Remove opaque pointer types.

ZeroIntensity · ZeroIntensity · commit a767e43f31b4 · 2026-04-19T12:15:23.000-04:00
diff --git a/Include/cpython/pystate.h b/Include/cpython/pystate.h
@@ -329,52 +329,24 @@ PyAPI_FUNC(_PyFrameEvalFunction) _PyInterpreterState_GetEvalFrameFunc(
 PyAPI_FUNC(void) _PyInterpreterState_SetEvalFrameFunc(
     PyInterpreterState *interp,
     _PyFrameEvalFunction eval_frame);
-
-/* Interpreter guards */
-
-typedef uintptr_t PyInterpreterGuard;
-typedef uintptr_t PyInterpreterView;
-
-
-PyAPI_FUNC(PyInterpreterGuard) PyInterpreterGuard_FromCurrent(void);
-PyAPI_FUNC(PyInterpreterGuard) PyInterpreterGuard_Copy(PyInterpreterGuard guard);
-PyAPI_FUNC(void) PyInterpreterGuard_Release(PyInterpreterGuard guard);
-PyAPI_FUNC(PyInterpreterState *) PyInterpreterGuard_GetInterpreter(PyInterpreterGuard guard);
-PyAPI_FUNC(PyInterpreterGuard) PyInterpreterGuard_FromView(PyInterpreterView view);
-
-#ifdef Py_DEBUG
-#define PyInterpreterGuard_Release(guard) do {    \
-    PyInterpreterGuard_Release(guard);            \
-    guard = 0;                                    \
-} while (0)
-#endif
-
-/* Interpreter views */
-
-typedef struct _PyInterpreterView {
-    int64_t id;
-    Py_ssize_t refcount;
-} _PyInterpreterView;
-
-PyAPI_FUNC(PyInterpreterView) PyInterpreterView_FromCurrent(void);
-PyAPI_FUNC(PyInterpreterView) PyInterpreterView_Copy(PyInterpreterView view);
-PyAPI_FUNC(void) PyInterpreterView_Close(PyInterpreterView view);
-PyAPI_FUNC(PyInterpreterView) PyUnstable_InterpreterView_FromDefault(void);
-
-
-#ifdef Py_DEBUG
-#define PyInterpreterView_Close(view) do {    \
-    PyInterpreterView_Close(view);            \
-    view = 0;                                 \
-} while (0)
-#endif
-
-PyAPI_FUNC(PyThreadState *) PyThreadState_Ensure(PyInterpreterGuard guard);
-
-PyAPI_FUNC(void) PyThreadState_Release(PyThreadState *tstate);
-
 PyAPI_FUNC(void) _PyInterpreterState_SetEvalFrameAllowSpecialization(
     PyInterpreterState *interp,
     int allow_specialization);
 PyAPI_FUNC(int) _PyInterpreterState_IsSpecializationEnabled(
     PyInterpreterState *interp);
+
+/* PEP 788 -- Interpreter guards and views. */
+
+typedef struct _PyInterpreterGuard PyInterpreterGuard;
+typedef struct _PyInterpreterView PyInterpreterView;
+
+PyAPI_FUNC(PyInterpreterGuard *) PyInterpreterGuard_FromCurrent(void);
+PyAPI_FUNC(void) PyInterpreterGuard_Close(PyInterpreterGuard *guard);
+PyAPI_FUNC(PyInterpreterGuard *) PyInterpreterGuard_FromView(PyInterpreterView *view);
+
+PyAPI_FUNC(PyInterpreterView *) PyInterpreterView_FromCurrent(void);
+PyAPI_FUNC(void) PyInterpreterView_Close(PyInterpreterView *view);
+PyAPI_FUNC(PyInterpreterView *) PyInterpreterView_FromMain(void);
+
+PyAPI_FUNC(PyThreadState *) PyThreadState_Ensure(PyInterpreterGuard *guard);
+PyAPI_FUNC(void) PyThreadState_Release(PyThreadState *tstate);
diff --git a/Include/internal/pycore_pystate.h b/Include/internal/pycore_pystate.h
@@ -338,8 +338,20 @@ _Py_RecursionLimit_GetMargin(PyThreadState *tstate)
 #endif
 }
 
+/* PEP 788 structures. */
+
+struct _PyInterpreterGuard {
+    PyInterpreterState *interp;
+};
+
+struct _PyInterpreterView {
+    int64_t id;
+    Py_ssize_t refcount;
+};
+
 // Exports for '_testinternalcapi' shared extension
 PyAPI_FUNC(Py_ssize_t) _PyInterpreterState_GuardCountdown(PyInterpreterState *interp);
+PyAPI_FUNC(PyInterpreterState *) _PyInterpreterGuard_GetInterpreter(PyInterpreterGuard *guard);
 
 #ifdef __cplusplus
 }
diff --git a/Modules/_testcapimodule.c b/Modules/_testcapimodule.c
@@ -2609,18 +2609,15 @@ create_managed_weakref_nogc_type(PyObject *self, PyObject *Py_UNUSED(args))
 static void
 test_interp_guards_common(void)
 {
-    PyInterpreterState *interp = PyInterpreterState_Get();
-    PyInterpreterGuard guard = PyInterpreterGuard_FromCurrent();
-    assert(guard != 0);
-    assert(PyInterpreterGuard_GetInterpreter(guard) == interp);
+    PyInterpreterGuard *guard = PyInterpreterGuard_FromCurrent();
+    assert(guard != NULL);
 
-    PyInterpreterGuard guard_2 = PyInterpreterGuard_Copy(guard);
-    assert(guard_2 != 0);
-    assert(PyInterpreterGuard_GetInterpreter(guard_2) == interp);
+    PyInterpreterGuard *guard_2 = PyInterpreterGuard_FromCurrent();
+    assert(guard_2 != NULL);
 
-    // We can close the references in any order
-    PyInterpreterGuard_Release(guard_2);
-    PyInterpreterGuard_Release(guard);
+    // We can close the guards in any order
+    PyInterpreterGuard_Close(guard_2);
+    PyInterpreterGuard_Close(guard);
 }
 
 static PyObject *
@@ -2657,25 +2654,25 @@ test_interpreter_guards(PyObject *self, PyObject *unused)
 static PyObject *
 test_thread_state_ensure_nested(PyObject *self, PyObject *unused)
 {
-    PyInterpreterGuard guard = PyInterpreterGuard_FromCurrent();
-    if (guard == 0) {
+    PyInterpreterGuard *guard = PyInterpreterGuard_FromCurrent();
+    if (guard == NULL) {
         return NULL;
     }
     PyThreadState *save_tstate = PyThreadState_Swap(NULL);
     assert(PyGILState_GetThisThreadState() == save_tstate);
-    PyThreadState * thread_views[10];
+    PyThreadState *thread_states[10];
 
     for (int i = 0; i < 10; ++i) {
         // Test reactivation of the detached tstate.
-        thread_views[i] = PyThreadState_Ensure(guard);
-        if (thread_views[i] == 0) {
-            PyInterpreterGuard_Release(guard);
+        thread_states[i] = PyThreadState_Ensure(guard);
+        if (thread_states[i] == 0) {
+            PyInterpreterGuard_Close(guard);
             return PyErr_NoMemory();
         }
 
         // No new thread state should've been created.
         assert(PyThreadState_Get() == save_tstate);
-        PyThreadState_Release(thread_views[i]);
+        PyThreadState_Release(thread_states[i]);
     }
 
     assert(PyThreadState_GetUnchecked() == NULL);
@@ -2684,11 +2681,11 @@ test_thread_state_ensure_nested(PyObject *self, PyObject *unused)
     // If the (detached) gilstate matches the interpreter, then it shouldn't
     // create a new thread state.
     for (int i = 0; i < 10; ++i) {
-        thread_views[i] = PyThreadState_Ensure(guard);
-        if (thread_views[i] == 0) {
+        thread_states[i] = PyThreadState_Ensure(guard);
+        if (thread_states[i] == 0) {
             // This will technically leak other thread states, but it doesn't
             // matter because this is a test.
-            PyInterpreterGuard_Release(guard);
+            PyInterpreterGuard_Close(guard);
             return PyErr_NoMemory();
         }
 
@@ -2697,23 +2694,23 @@ test_thread_state_ensure_nested(PyObject *self, PyObject *unused)
 
     for (int i = 0; i < 10; ++i) {
         assert(PyThreadState_Get() == save_tstate);
-        PyThreadState_Release(thread_views[i]);
+        PyThreadState_Release(thread_states[i]);
     }
 
     assert(PyThreadState_GetUnchecked() == NULL);
-    PyInterpreterGuard_Release(guard);
+    PyInterpreterGuard_Close(guard);
     PyThreadState_Swap(save_tstate);
     Py_RETURN_NONE;
 }
 
 static PyObject *
 test_thread_state_ensure_crossinterp(PyObject *self, PyObject *unused)
 {
-    PyInterpreterGuard guard = PyInterpreterGuard_FromCurrent();
+    PyInterpreterGuard *guard = PyInterpreterGuard_FromCurrent();
     PyThreadState *save_tstate = PyThreadState_Swap(NULL);
     PyThreadState *interp_tstate = Py_NewInterpreter();
     if (interp_tstate == NULL) {
-        PyInterpreterGuard_Release(guard);
+        PyInterpreterGuard_Close(guard);
         return PyErr_NoMemory();
     }
 
@@ -2730,37 +2727,36 @@ test_thread_state_ensure_crossinterp(PyObject *self, PyObject *unused)
        interp = interpreters.create()
        interp.exec(some_func)
        */
-    PyThreadState * thread_view = PyThreadState_Ensure(guard);
-    if (thread_view == 0) {
-        PyInterpreterGuard_Release(guard);
+    PyThreadState *thread_state = PyThreadState_Ensure(guard);
+    if (thread_state == NULL) {
+        PyInterpreterGuard_Close(guard);
         return PyErr_NoMemory();
     }
 
     PyThreadState *ensured_tstate = PyThreadState_Get();
     assert(ensured_tstate != save_tstate);
-    assert(PyInterpreterState_Get() == PyInterpreterGuard_GetInterpreter(guard));
     assert(PyGILState_GetThisThreadState() == ensured_tstate);
 
     // Now though, we should reactivate the thread state
-    PyThreadState * other_thread_view = PyThreadState_Ensure(guard);
-    if (other_thread_view == 0) {
-        PyThreadState_Release(thread_view);
-        PyInterpreterGuard_Release(guard);
+    PyThreadState *other_thread_state = PyThreadState_Ensure(guard);
+    if (other_thread_state == NULL) {
+        PyThreadState_Release(thread_state);
+        PyInterpreterGuard_Close(guard);
         return PyErr_NoMemory();
     }
 
     assert(PyThreadState_Get() == ensured_tstate);
-    PyThreadState_Release(other_thread_view);
+    PyThreadState_Release(other_thread_state);
 
     // Ensure that we're restoring the prior thread state
-    PyThreadState_Release(thread_view);
+    PyThreadState_Release(thread_state);
     assert(PyThreadState_Get() == interp_tstate);
     assert(PyGILState_GetThisThreadState() == interp_tstate);
 
     PyThreadState_Swap(interp_tstate);
     Py_EndInterpreter(interp_tstate);
 
-    PyInterpreterGuard_Release(guard);
+    PyInterpreterGuard_Close(guard);
     PyThreadState_Swap(save_tstate);
     Py_RETURN_NONE;
 }
@@ -2774,20 +2770,20 @@ test_interp_view_after_shutdown(PyObject *self, PyObject *unused)
         return PyErr_NoMemory();
     }
 
-    PyInterpreterView view = PyInterpreterView_FromCurrent();
-    if (view == 0) {
+    PyInterpreterView *view = PyInterpreterView_FromCurrent();
+    if (view == NULL) {
         return PyErr_NoMemory();
     }
 
     // As a sanity check, ensure that the view actually works
-    PyInterpreterGuard guard = PyInterpreterGuard_FromView(view);
-    PyInterpreterGuard_Release(guard);
+    PyInterpreterGuard *guard = PyInterpreterGuard_FromView(view);
+    PyInterpreterGuard_Close(guard);
 
     // Now, destroy the interpreter and try to acquire a lock from a view.
     // It should fail.
     Py_EndInterpreter(interp_tstate);
     guard = PyInterpreterGuard_FromView(view);
-    assert(guard == 0);
+    assert(guard == NULL);
 
     PyThreadState_Swap(save_tstate);
     Py_RETURN_NONE;
diff --git a/Modules/_testinternalcapi.c b/Modules/_testinternalcapi.c
@@ -2883,15 +2883,15 @@ test_interp_guard_countdown(PyObject *self, PyObject *unused)
 {
     PyInterpreterState *interp = PyInterpreterState_Get();
     assert(_PyInterpreterState_GuardCountdown(interp) == 0);
-    PyInterpreterGuard guards[NUM_GUARDS];
+    PyInterpreterGuard *guards[NUM_GUARDS];
     for (int i = 0; i < NUM_GUARDS; ++i) {
         guards[i] = PyInterpreterGuard_FromCurrent();
         assert(guards[i] != 0);
         assert(_PyInterpreterState_GuardCountdown(interp) == i + 1);
     }
 
     for (int i = 0; i < NUM_GUARDS; ++i) {
-        PyInterpreterGuard_Release(guards[i]);
+        PyInterpreterGuard_Close(guards[i]);
         assert(_PyInterpreterState_GuardCountdown(interp) == (NUM_GUARDS - i - 1));
     }
 
@@ -2902,23 +2902,23 @@ static PyObject *
 test_interp_view_countdown(PyObject *self, PyObject *unused)
 {
     PyInterpreterState *interp = PyInterpreterState_Get();
-    PyInterpreterView view = PyInterpreterView_FromCurrent();
-    if (view == 0) {
+    PyInterpreterView *view = PyInterpreterView_FromCurrent();
+    if (view == NULL) {
         return NULL;
     }
     assert(_PyInterpreterState_GuardCountdown(interp) == 0);
 
-    PyInterpreterGuard guards[NUM_GUARDS];
+    PyInterpreterGuard *guards[NUM_GUARDS];
 
     for (int i = 0; i < NUM_GUARDS; ++i) {
         guards[i] = PyInterpreterGuard_FromView(view);
         assert(guards[i] != 0);
-        assert(PyInterpreterGuard_GetInterpreter(guards[i]) == interp);
+        assert(_PyInterpreterGuard_GetInterpreter(guards[i]) == interp);
         assert(_PyInterpreterState_GuardCountdown(interp) == i + 1);
     }
 
     for (int i = 0; i < NUM_GUARDS; ++i) {
-        PyInterpreterGuard_Release(guards[i]);
+        PyInterpreterGuard_Close(guards[i]);
         assert(_PyInterpreterState_GuardCountdown(interp) == (NUM_GUARDS - i - 1));
     }
 
diff --git a/Programs/_testembed.c b/Programs/_testembed.c
@@ -2682,15 +2682,15 @@ const char *THREAD_CODE = \
     "fib(10)";
 
 typedef struct {
-    PyInterpreterGuard guard;
+    PyInterpreterGuard *guard;
     int done;
 } ThreadData;
 
 static void
 do_tstate_ensure(void *arg)
 {
     ThreadData *data = (ThreadData *)arg;
-    PyThreadState * refs[4];
+    PyThreadState *refs[4];
     refs[0] = PyThreadState_Ensure(data->guard);
     refs[1] = PyThreadState_Ensure(data->guard);
     refs[2] = PyThreadState_Ensure(data->guard);
@@ -2707,7 +2707,7 @@ do_tstate_ensure(void *arg)
     PyThreadState_Release(refs[2]);
     PyThreadState_Release(refs[1]);
     PyThreadState_Release(refs[0]);
-    PyInterpreterGuard_Release(data->guard);
+    PyInterpreterGuard_Close(data->guard);
     data->done = 1;
 }
 
@@ -2717,14 +2717,14 @@ test_thread_state_ensure(void)
     _testembed_initialize();
     PyThread_handle_t handle;
     PyThread_ident_t ident;
-    PyInterpreterGuard guard = PyInterpreterGuard_FromCurrent();
-    if (guard == 0) {
+    PyInterpreterGuard *guard = PyInterpreterGuard_FromCurrent();
+    if (guard == NULL) {
         return -1;
     };
     ThreadData data = { guard };
     if (PyThread_start_joinable_thread(do_tstate_ensure, &data,
                                        &ident, &handle) < 0) {
-        PyInterpreterGuard_Release(guard);
+        PyInterpreterGuard_Close(guard);
         return -1;
     }
     // We hold an interpreter guard, so we don't
@@ -2741,18 +2741,18 @@ test_main_interpreter_view(void)
     _testembed_initialize();
 
     // Main interpreter is initialized and ready.
-    PyInterpreterView view = PyUnstable_InterpreterView_FromDefault();
-    assert(view != 0);
+    PyInterpreterView *view = PyInterpreterView_FromMain();
+    assert(view != NULL);
 
-    PyInterpreterGuard guard = PyInterpreterGuard_FromView(view);
-    assert(guard != 0);
-    PyInterpreterGuard_Release(guard);
+    PyInterpreterGuard *guard = PyInterpreterGuard_FromView(view);
+    assert(guard != NULL);
+    PyInterpreterGuard_Close(guard);
 
     Py_Finalize();
 
     // We shouldn't be able to get locks for the interpreter now
     guard = PyInterpreterGuard_FromView(view);
-    assert(guard == 0);
+    assert(guard == NULL);
 
     PyInterpreterView_Close(view);
 
diff --git a/Python/pystate.c b/Python/pystate.c
