bpo-36487: Make C-API docs clear about what the main interpreter is. (gh-15080)

(cherry picked from commit 854d0a4b98b13629252e21edaf2b785b429e5135) (gh-12666)

Co-authored-by: Joannah Nanjekye <33177550+nanjekyejoannah@users.noreply.github.com>

diff --git a/Doc/c-api/init.rst b/Doc/c-api/init.rst
index a0ac4d21d1393659a1982468b52300c1577826f1..4985a1d867e2ad28a3de320cf7f386deb2c7594f 100644 (file)
--- a/Doc/c-api/init.rst
+++ b/Doc/c-api/init.rst
@@ -1141,10 +1141,18 @@ Sub-interpreter support
 
 While in most uses, you will only embed a single Python interpreter, there
 are cases where you need to create several independent interpreters in the
-same process and perhaps even in the same thread.  Sub-interpreters allow
-you to do that.  You can switch between sub-interpreters using the
-:c:func:`PyThreadState_Swap` function.  You can create and destroy them
-using the following functions:
+same process and perhaps even in the same thread. Sub-interpreters allow
+you to do that.
+
+The "main" interpreter is the first one created when the runtime initializes.
+It is usually the only Python interpreter in a process.  Unlike sub-interpreters,
+the main interpreter has unique process-global responsibilities like signal
+handling.  It is also responsible for execution during runtime initialization and
+is usually the active interpreter during runtime finalization.  The
+:c:func:`PyInterpreterState_Main` funtion returns a pointer to its state.
+
+You can switch between sub-interpreters using the :c:func:`PyThreadState_Swap`
+function. You can create and destroy them using the following functions:
 
 
 .. c:function:: PyThreadState* Py_NewInterpreter()

diff --git a/Misc/NEWS.d/next/Documentation/2019-04-02-19-23-00.bpo-36487.Jg6-MG.rst b/Misc/NEWS.d/next/Documentation/2019-04-02-19-23-00.bpo-36487.Jg6-MG.rst
new file mode 100755 (executable)
index 0000000..c8eb05b
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2019-04-02-19-23-00.bpo-36487.Jg6-MG.rst
@@ -0,0 +1 @@
+Make C-API docs clear about what the "main" interpreter is.
\ No newline at end of file