bpo-38816: Add notes in the C-API docs about fork in subinterpreters. (GH-17176)
The C-API docs are a bit sparse on the interplay between C `fork()` and the CPython runtime. This change adds some more information on the subject.
https://bugs.python.org/issue38816
diff --git a/Doc/c-api/sys.rst b/Doc/c-api/sys.rst
index 212f4d1..d3bbee2 100644
--- a/Doc/c-api/sys.rst
+++ b/Doc/c-api/sys.rst
@@ -33,6 +33,12 @@
that clones the current process.
Only available on systems where :c:func:`fork` is defined.
+ .. warning::
+ The C :c:func:`fork` call should only be made from the
+ :ref:`"main" thread <fork-and-threads>` (of the
+ :ref:`"main" interpreter <sub-interpreter-support>`). The same is
+ true for ``PyOS_BeforeFork()``.
+
.. versionadded:: 3.7
@@ -44,6 +50,12 @@
of whether process cloning was successful.
Only available on systems where :c:func:`fork` is defined.
+ .. warning::
+ The C :c:func:`fork` call should only be made from the
+ :ref:`"main" thread <fork-and-threads>` (of the
+ :ref:`"main" interpreter <sub-interpreter-support>`). The same is
+ true for ``PyOS_AfterFork_Parent()``.
+
.. versionadded:: 3.7
@@ -55,6 +67,12 @@
any chance the process will call back into the Python interpreter.
Only available on systems where :c:func:`fork` is defined.
+ .. warning::
+ The C :c:func:`fork` call should only be made from the
+ :ref:`"main" thread <fork-and-threads>` (of the
+ :ref:`"main" interpreter <sub-interpreter-support>`). The same is
+ true for ``PyOS_AfterFork_Child()``.
+
.. versionadded:: 3.7
.. seealso::