Allow per-interpreter internals/local_internals

Author: b-pass

CMakeLists.txt

@@ -92,6 +92,7 @@ option(PYBIND11_DISABLE_HANDLE_TYPE_NAME_DEFAULT_IMPLEMENTATION
        "To enforce that a handle_type_name<> specialization exists" OFF)
 option(PYBIND11_SIMPLE_GIL_MANAGEMENT
        "Use simpler GIL management logic that does not support disassociation" OFF)
+option(PYBIND11_SUBINTERPRETER_SUPPORT "Enable support for sub-interpreters" OFF)
 option(PYBIND11_NUMPY_1_ONLY
        "Disable NumPy 2 support to avoid changes to previous pybind11 versions." OFF)
 set(PYBIND11_INTERNALS_VERSION
@@ -105,6 +106,9 @@ endif()
 if(PYBIND11_SIMPLE_GIL_MANAGEMENT)
   add_compile_definitions(PYBIND11_SIMPLE_GIL_MANAGEMENT)
 endif()
+if(PYBIND11_SUBINTERPRETER_SUPPORT)
+  add_compile_definitions(PYBIND11_SUBINTERPRETER_SUPPORT)
+endif()
 if(PYBIND11_NUMPY_1_ONLY)
   add_compile_definitions(PYBIND11_NUMPY_1_ONLY)
 endif()

include/pybind11/detail/internals.h

@@ -260,7 +260,25 @@ struct type_info {
 /// Each module locally stores a pointer to the `internals` data. The data
 /// itself is shared among modules with the same `PYBIND11_INTERNALS_ID`.
 inline internals **&get_internals_pp() {
+#if defined(PYPY_VERSION) || defined(GRAALVM_PYTHON) || PY_VERSION_HEX < 0x030C0000               \
+    || !defined(PYBIND11_SUBINTERPRETER_SUPPORT)
     static internals **internals_pp = nullptr;
+#else
+    static thread_local internals **internals_pp = nullptr;
+    // This is one per interpreter, we cache it but if the thread changed
+    // then we need to invalidate our cache
+    // the caller will find the right value and set it if its null
+    static thread_local PyThreadState *tstate_cached = nullptr;
+#    if PY_VERSION_HEX < 0x030D0000
+    PyThreadState *tstate = _PyThreadState_UncheckedGet();
+#    else
+    PyThreadState *tstate = PyThreadState_GetUnchecked();
+#    endif
+    if (tstate != tstate_cached) {
+        tstate_cached = tstate;
+        internals_pp = nullptr;
+    }
+#endif
     return internals_pp;
 }
 
@@ -427,9 +445,6 @@ PYBIND11_NOINLINE internals &get_internals() {
         return **internals_pp;
     }
 
-#if defined(PYBIND11_SIMPLE_GIL_MANAGEMENT)
-    gil_scoped_acquire gil;
-#else
     // Ensure that the GIL is held since we will need to make Python calls.
     // Cannot use py::gil_scoped_acquire here since that constructor calls get_internals.
     struct gil_scoped_acquire_local {
@@ -439,7 +454,7 @@ PYBIND11_NOINLINE internals &get_internals() {
         ~gil_scoped_acquire_local() { PyGILState_Release(state); }
         const PyGILState_STATE state;
     } gil;
-#endif
+
     error_scope err_scope;
 
     dict state_dict = get_python_state_dict();
@@ -455,7 +470,12 @@ PYBIND11_NOINLINE internals &get_internals() {
         // libc++ with CPython doesn't require this (types are explicitly exported)
         // libc++ with PyPy still need it, awaiting further investigation
 #if !defined(__GLIBCXX__)
-        (*internals_pp)->registered_exception_translators.push_front(&translate_local_exception);
+        if ((*internals_pp)->registered_exception_translators.empty()
+            || (*internals_pp)->registered_exception_translators.front()
+                   != &translate_local_exception) {
+            (*internals_pp)
+                ->registered_exception_translators.push_front(&translate_local_exception);
+        }
 #endif
     } else {
         if (!internals_pp) {
@@ -515,7 +535,61 @@ inline local_internals &get_local_internals() {
     // static deinitialization fiasco. In order to avoid it we avoid destruction of the
     // local_internals static. One can read more about the problem and current solution here:
     // https://google.github.io/styleguide/cppguide.html#Static_and_Global_Variables
+
+#if defined(PYPY_VERSION) || defined(GRAALVM_PYTHON) || PY_VERSION_HEX < 0x030C0000               \
+    || !defined(PYBIND11_SUBINTERPRETER_SUPPORT)
     static auto *locals = new local_internals();
+#else
+    static thread_local local_internals *locals = nullptr;
+    // This is one per interpreter, we cache it but if the interpreter changed
+    // then we need to invalidate our cache and re-fetch from the state dict
+    static thread_local PyThreadState *tstate_cached = nullptr;
+#    if PY_VERSION_HEX < 0x030D0000
+    PyThreadState *tstate = _PyThreadState_UncheckedGet();
+#    else
+    PyThreadState *tstate = PyThreadState_GetUnchecked();
+#    endif
+    if (!tstate) {
+        pybind11_fail(
+            "pybind11::detail::get_local_internals() called without a current python thread");
+    }
+    if (tstate != tstate_cached) {
+        // we create a unique value at first run which is based on a pointer to
+        // a (non-thread_local) static value in this function, then multiple
+        // loaded modules using this code will still each have a unique key.
+        static const std::string this_module_idstr
+            = PYBIND11_MODULE_LOCAL_ID
+              + std::to_string(reinterpret_cast<uintptr_t>(&this_module_idstr));
+
+        // Ensure that the GIL is held since we will need to make Python calls.
+        // Cannot use py::gil_scoped_acquire here since that constructor calls get_internals.
+        struct gil_scoped_acquire_local {
+            gil_scoped_acquire_local() : state(PyGILState_Ensure()) {}
+            gil_scoped_acquire_local(const gil_scoped_acquire_local &) = delete;
+            gil_scoped_acquire_local &operator=(const gil_scoped_acquire_local &) = delete;
+            ~gil_scoped_acquire_local() { PyGILState_Release(state); }
+            const PyGILState_STATE state;
+        } gil;
+
+        error_scope err_scope;
+        dict state_dict = get_python_state_dict();
+        object local_capsule = reinterpret_steal<object>(
+            dict_getitemstringref(state_dict.ptr(), this_module_idstr.c_str()));
+        if (!local_capsule) {
+            locals = new local_internals();
+            state_dict[this_module_idstr.c_str()] = capsule(reinterpret_cast<void *>(locals));
+        } else {
+            void *ptr = PyCapsule_GetPointer(local_capsule.ptr(), nullptr);
+            if (!ptr) {
+                raise_from(PyExc_SystemError, "pybind11::detail::get_local_internals() FAILED");
+                throw error_already_set();
+            }
+            locals = reinterpret_cast<local_internals *>(ptr);
+        }
+        tstate_cached = tstate;
+    }
+#endif
+
     return *locals;
 }
 

include/pybind11/pybind11.h

@@ -1255,6 +1255,26 @@ class mod_gil_not_used {
     bool flag_;
 };
 
+// Use to activate Py_MOD_PER_INTERPRETER_GIL_SUPPORTED
+class mod_per_interpreter_gil {
+public:
+    explicit mod_per_interpreter_gil(bool flag = true) : flag_(flag) {}
+    bool flag() const { return flag_; }
+
+private:
+    bool flag_;
+};
+
+// Use to activate Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED
+class mod_multi_interpreter_one_gil {
+public:
+    explicit mod_multi_interpreter_one_gil(bool flag = true) : flag_(flag) {}
+    bool flag() const { return flag_; }
+
+private:
+    bool flag_;
+};
+
 PYBIND11_NAMESPACE_BEGIN(detail)
 
 inline bool gil_not_used_option() { return false; }
@@ -1269,6 +1289,35 @@ inline bool gil_not_used_option(F &&, O &&...o) {
     return false || gil_not_used_option(o...);
 }
 
+#ifdef Py_mod_multiple_interpreters
+inline void *multi_interp_option() { return Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED; }
+#    ifdef PYBIND11_SUBINTERPRETER_SUPPORT
+template <typename F, typename... O>
+void *multi_interp_option(F &&, O &&...o);
+template <typename... O>
+void *multi_interp_option(mod_multi_interpreter_one_gil f, O &&...o);
+template <typename... O>
+inline void *multi_interp_option(mod_per_interpreter_gil f, O &&...o) {
+    if (f.flag()) {
+        return Py_MOD_PER_INTERPRETER_GIL_SUPPORTED;
+    }
+    return multi_interp_option(o...);
+}
+template <typename... O>
+inline void *multi_interp_option(mod_multi_interpreter_one_gil f, O &&...o) {
+    void *others = multi_interp_option(o...);
+    if (!f.flag() || others == Py_MOD_PER_INTERPRETER_GIL_SUPPORTED) {
+        return others;
+    }
+    return Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED;
+}
+#    endif
+template <typename F, typename... O>
+inline void *multi_interp_option(F &&, O &&...o) {
+    return multi_interp_option(o...);
+}
+#endif
+
 PYBIND11_NAMESPACE_END(detail)
 
 /// Wrapper for Python extension modules
@@ -1411,7 +1460,7 @@ class module_ : public object {
 
         ``def`` should point to a statically allocated module_def.
         ``slots`` must point to an initialized array of slots with space for at
-           least one additional slot to be populated based on the options.
+           least two additional slots to be populated based on the options.
     \endrst */
     template <typename... Options>
     static object init_module_def(const char *name,
@@ -1426,6 +1475,18 @@ class module_ : public object {
 
         bool nogil PYBIND11_MAYBE_UNUSED = detail::gil_not_used_option(options...);
 
+#ifdef Py_mod_multiple_interpreters
+        slots[i].slot = Py_mod_multiple_interpreters;
+        slots[i].value = detail::multi_interp_option(options...);
+        if (nogil && slots[i].value == Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED) {
+            // if you support free threading and multi-interpreters,
+            // then you definitely also support per-interpreter GIL
+            // even if you don't know it.
+            slots[i].value = Py_MOD_PER_INTERPRETER_GIL_SUPPORTED;
+        }
+        ++i;
+#endif
+
         if (nogil) {
 #ifdef Py_mod_gil
             slots[i].slot = Py_mod_gil;

tests/test_embed/CMakeLists.txt

@@ -29,6 +29,7 @@ endif()
 find_package(Threads REQUIRED)
 
 add_executable(test_embed catch.cpp test_interpreter.cpp)
+target_compile_definitions(test_embed PRIVATE "PYBIND11_SUBINTERPRETER_SUPPORT")
 pybind11_enable_warnings(test_embed)
 
 target_link_libraries(test_embed PRIVATE pybind11::embed Catch2::Catch2 Threads::Threads)
@@ -44,6 +45,7 @@ add_custom_target(
   WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}")
 
 pybind11_add_module(external_module THIN_LTO external_module.cpp)
+target_compile_definitions(external_module PRIVATE "PYBIND11_SUBINTERPRETER_SUPPORT")
 set_target_properties(external_module PROPERTIES LIBRARY_OUTPUT_DIRECTORY
                                                  "${CMAKE_CURRENT_BINARY_DIR}")
 foreach(config ${CMAKE_CONFIGURATION_TYPES})

tests/test_embed/external_module.cpp

@@ -6,7 +6,7 @@ namespace py = pybind11;
  * modules aren't preserved over a finalize/initialize.
  */
 
-PYBIND11_MODULE(external_module, m, py::mod_gil_not_used()) {
+PYBIND11_MODULE(external_module, m, py::mod_gil_not_used(), py::mod_multi_interpreter_one_gil()) {
     class A {
     public:
         explicit A(int value) : v{value} {};

tests/test_embed/test_interpreter.cpp

@@ -323,6 +323,8 @@ TEST_CASE("Restart the interpreter") {
 }
 
 TEST_CASE("Subinterpreter") {
+    py::module_::import("external_module"); // in the main interpreter
+
     // Add tags to the modules in the main interpreter and test the basics.
     py::module_::import("__main__").attr("main_tag") = "main interpreter";
     {
@@ -338,11 +340,24 @@ TEST_CASE("Subinterpreter") {
     auto *main_tstate = PyThreadState_Get();
     auto *sub_tstate = Py_NewInterpreter();
 
-    // Subinterpreters get their own copy of builtins. detail::get_internals() still
-    // works by returning from the static variable, i.e. all interpreters share a single
-    // global pybind11::internals;
+    // Subinterpreters get their own copy of builtins.
     REQUIRE_FALSE(has_state_dict_internals_obj());
+
+#if defined(PYBIND11_SUBINTERPRETER_SUPPORT) && PY_VERSION_HEX >= 0x030C0000
+    // internals hasn't been populated yet, but will be different for the subinterpreter
+    REQUIRE_FALSE(has_pybind11_internals_static());
+
+    py::list sys_path = py::module_::import("sys").attr("path");
+    sys_path.append(py::str("."));
+
+    auto ext_int = py::module_::import("external_module").attr("internals_at")().cast<uintptr_t>();
+    py::detail::get_internals();
     REQUIRE(has_pybind11_internals_static());
+    REQUIRE(reinterpret_cast<uintptr_t>(*py::detail::get_internals_pp()) == ext_int);
+#else
+    // This static is still defined
+    REQUIRE(has_pybind11_internals_static());
+#endif
 
     // Modules tags should be gone.
     REQUIRE_FALSE(py::hasattr(py::module_::import("__main__"), "tag"));
@@ -354,12 +369,16 @@ TEST_CASE("Subinterpreter") {
         REQUIRE(m.attr("add")(1, 2).cast<int>() == 3);
     }
 
+    // The subinterpreter now has internals populated since we imported a pybind11 module
+    REQUIRE(has_pybind11_internals_static());
+
     // Restore main interpreter.
     Py_EndInterpreter(sub_tstate);
     PyThreadState_Swap(main_tstate);
 
     REQUIRE(py::hasattr(py::module_::import("__main__"), "main_tag"));
     REQUIRE(py::hasattr(py::module_::import("widget_module"), "extension_module_tag"));
+    REQUIRE(has_state_dict_internals_obj());
 }
 
 TEST_CASE("Execution frame") {