[3.12] gh-107306: Add a Doc Entry for Py_mod_multiple_interpreters (GH-107403)

Doc/c-api/init.rst

@@ -635,7 +635,7 @@
    :data:`sys.exec_prefix` to be empty.  It is up to the caller to modify these
    if required after calling :c:func:`Py_Initialize`.
 
    Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
    :c:expr:`wchar_*` string.
 
    The path argument is copied internally, so the caller may free it after the
@@ -750,7 +750,7 @@
      :data:`sys.path`, which is the same as prepending the current working
      directory (``"."``).
 
    Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
    :c:expr:`wchar_*` string.
 
    See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv`
@@ -786,7 +786,7 @@
    to ``1`` unless the :program:`python` interpreter was started with the
    :option:`-I`.
 
    Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
    :c:expr:`wchar_*` string.
 
    See also :c:member:`PyConfig.orig_argv` and :c:member:`PyConfig.argv`
@@ -812,7 +812,7 @@
    execution.  No code in the Python interpreter will change the contents of
    this storage.
 
    Use :c:func:`Py_DecodeLocale` to decode a bytes string to get a
    :c:expr:`wchar_*` string.
 
    .. deprecated:: 3.11
@@ -1136,7 +1136,7 @@
       You can use :c:func:`!_Py_IsFinalizing` or :func:`sys.is_finalizing` to
       check if the interpreter is in process of being finalized before calling
       this function to avoid unwanted termination.
 
 .. c:function:: void PyGILState_Release(PyGILState_STATE)
 
    Release any resources previously acquired.  After this call, Python's state will
@@ -1147,7 +1147,7 @@
    Every call to :c:func:`PyGILState_Ensure` must be matched by a call to
    :c:func:`PyGILState_Release` on the same thread.
 
 
 .. c:function:: PyThreadState* PyGILState_GetThisThreadState()
 
    Get the current thread state for this thread.  May return ``NULL`` if no
@@ -1249,7 +1249,7 @@
    must be held.
 
    .. versionchanged:: 3.9
       This function now calls the :c:member:`PyThreadState.on_delete` callback.
       Previously, that happened in :c:func:`PyThreadState_Delete`.
 
 
@@ -1451,7 +1451,7 @@
       instead.
 
    .. note::
       Calling this function from a thread when the runtime is finalizing
       will terminate the thread, even if the thread was not created by Python.
       You can use :c:func:`_Py_IsFinalizing` or :func:`sys.is_finalizing` to
       check if the interpreter is in process of being finalized before calling
@@ -1555,6 +1555,7 @@
       in any thread where the sub-interpreter is currently active.
       Otherwise only multi-phase init extension modules
       (see :pep:`489`) may be imported.
+      (Also see :c:macro:`Py_mod_multiple_interpreters`.)
 
       This must be ``1`` (non-zero) if
       :c:member:`~PyInterpreterConfig.use_main_obmalloc` is ``0``.
@@ -1906,7 +1907,7 @@
 
 .. c:var:: int PyTrace_LINE
 
    The value passed as the *what* parameter to a :c:type:`Py_tracefunc` function
    (but not a profiling function) when a line-number event is being reported.
    It may be disabled for a frame by setting :attr:`f_trace_lines` to *0* on that frame.
 
@@ -1937,7 +1938,7 @@
 
 .. c:var:: int PyTrace_OPCODE
 
    The value for the *what* parameter to :c:type:`Py_tracefunc` functions (but not
    profiling functions) when a new opcode is about to be executed.  This event is
    not emitted by default: it must be explicitly requested by setting
    :attr:`f_trace_opcodes` to *1* on the frame.

Doc/c-api/module.rst

@@ -376,6 +376,37 @@ The available slot types are:
    If multiple ``Py_mod_exec`` slots are specified, they are processed in the
    order they appear in the *m_slots* array.
 
+.. c:macro:: Py_mod_multiple_interpreters
+
+   Specifies one of the following values:
+
+   .. c:macro:: Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED
+
+      The module does not support being imported in subinterpreters.
+
+   .. c:macro:: Py_MOD_MULTIPLE_INTERPRETERS_SUPPORTED
+
+      The module supports being imported in subinterpreters,
+      but only when they share the main interpreter's GIL.
+      (See :ref:`isolating-extensions-howto`.)
+
+   .. c:macro:: Py_MOD_PER_INTERPRETER_GIL_SUPPORTED
+
+      The module supports being imported in subinterpreters,
+      even when they have their own GIL.
+      (See :ref:`isolating-extensions-howto`.)
+
+   This slot determines whether or not importing this module
+   in a subinterpreter will fail.
+
+   Multiple ``Py_mod_multiple_interpreters`` slots may not be specified
+   in one module definition.
+
+   If ``Py_mod_multiple_interpreters`` is not specified, the import
+   machinery defaults to ``Py_MOD_MULTIPLE_INTERPRETERS_NOT_SUPPORTED``.
+
+   .. versionadded:: 3.12
+
 See :PEP:`489` for more details on multi-phase initialization.
 
 Low-level module creation functions

Doc/howto/isolating-extensions.rst

@@ -1,5 +1,7 @@
 .. highlight:: c
 
+.. _isolating-extensions-howto:
+
 ***************************
 Isolating Extension Modules
 ***************************