gh-144748: Document 3.12 and 3.14 changes to PyErr_CheckSignals

Doc/c-api/exceptions.rst

@@ -686,8 +686,9 @@
    other pending signals may not have been handled yet: they will be on the
    next :c:func:`PyErr_CheckSignals()` invocation).
 
-   If the function is called from a non-main thread, or under a non-main
-   Python interpreter, it does nothing and returns ``0``.
+   This function may invoke the garbage collector or execute a :ref:`remote
+   debugger <remote-debugging>` script, regardless of the calling thread
+   or Python interpreter.
 
    This function can be called by long-running C code that wants to
    be interruptible by user requests (such as by pressing Ctrl-C).
@@ -696,6 +697,51 @@
       The default Python signal handler for :c:macro:`!SIGINT` raises the
       :exc:`KeyboardInterrupt` exception.
 
+   .. versionchanged:: 3.12
+      This function may now invoke the garbage collector.
+
+   .. versionchanged:: 3.14
+      This function may now execute a remote debugger script, if remote
+      debugging is enabled.
+   Handle external interruptions, such as signals (including :kbd:`Ctrl-C`),
+   or activating a debugger, whose processing has been delayed until it is safe
+   to run Python code and/or raise exceptions.
+   The function should be called by long-running C code frequently
+   enough so that the response appears immediate to humans.
+
+   Handlers invoked by this function currently include:
+
+   - Signal handlers, including Python functions registered using
+     the :mod:`signal` module.
+
+     Signal handlers are only run in the main thread of the main interpreter.
+
+     (This is where the function got the name: originally, signals
+     were the only way to interrupt the interpreter.)
+
+   - Running the garbage collector, if necessary.
+
+   - Execuing a pending :ref:`remote debugger <remote-debugging>` script.
+
+   If any handler raises an exception, immediately return ``-1`` with that
+   exception set.
+   Any remaining interruptions are left to be processed on the next
+   :c:func:`PyErr_CheckSignals()` invocation, if appropriate.
+
+   If all handlers finish successfully, or there are no handlers to run,
+   return ``0``.
+
+   .. note::
+      The default Python signal handler for :py:data:`signal.SIGINT` raises the
+      :exc:`KeyboardInterrupt` exception.
+
+   .. versionchanged:: 3.12
+      This function may now invoke the garbage collector.
+
+   .. versionchanged:: 3.14
+      This function may now execute a remote debugger script, if remote
+      debugging is enabled.
+
 
 .. c:function:: void PyErr_SetInterrupt()