gh-84559: improve What's New entry for `multiprocessing` start method changes (#128173)

Co-authored-by: Gregory P. Smith <greg@krypto.org>
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
index 783cb025826483066f6d863a38835ff11158b100..1b1c6d74e5197c867dd293a627f1a11968be5509 100644 (file)
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -107,6 +107,8 @@ Contexts and start methods
 Depending on the platform, :mod:`multiprocessing` supports three ways
 to start a process.  These *start methods* are
 
+  .. _multiprocessing-start-method-spawn:
+
   *spawn*
     The parent process starts a fresh Python interpreter process.  The
     child process will only inherit those resources necessary to run
@@ -117,6 +119,8 @@ to start a process.  These *start methods* are
 
     Available on POSIX and Windows platforms.  The default on Windows and macOS.
 
+  .. _multiprocessing-start-method-fork:
+
   *fork*
     The parent process uses :func:`os.fork` to fork the Python
     interpreter.  The child process, when it begins, is effectively
@@ -137,6 +141,8 @@ to start a process.  These *start methods* are
        raise a :exc:`DeprecationWarning`. Use a different start method.
        See the :func:`os.fork` documentation for further explanation.
 
+  .. _multiprocessing-start-method-forkserver:
+
   *forkserver*
     When the program starts and selects the *forkserver* start method,
     a server process is spawned.  From then on, whenever a new process
@@ -2987,6 +2993,9 @@ Beware of replacing :data:`sys.stdin` with a "file like object"
 
     For more information, see :issue:`5155`, :issue:`5313` and :issue:`5331`
 
+.. _multiprocessing-programming-spawn:
+.. _multiprocessing-programming-forkserver:
+
 The *spawn* and *forkserver* start methods
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst
index eee9bc865357ee7c7f77f28c87582de3d79e416b..930fe718ac580a867748c9814dfff5cf6935aa89 100644 (file)
--- a/Doc/whatsnew/3.14.rst
+++ b/Doc/whatsnew/3.14.rst
@@ -70,6 +70,22 @@ Summary -- release highlights
 * :ref:`A new type of interpreter  <whatsnew314-tail-call>`
 
 
+Incompatible changes
+====================
+
+On platforms other than macOS and Windows, the default :ref:`start
+method <multiprocessing-start-methods>` for :mod:`multiprocessing`
+and :class:`~concurrent.futures.ProcessPoolExecutor` switches from
+*fork* to *forkserver*.
+
+See :ref:`(1) <whatsnew314-concurrent-futures-start-method>` and
+:ref:`(2) <whatsnew314-multiprocessing-start-method>` for details.
+
+If you encounter :exc:`NameError`\s or pickling errors coming out of
+:mod:`multiprocessing` or :mod:`concurrent.futures`, see the
+:ref:`forkserver restrictions <multiprocessing-programming-forkserver>`.
+
+
 New features
 ============
 
@@ -396,12 +412,26 @@ concurrent.futures
   same process) to Python code.  This is separate from the proposed API
   in :pep:`734`.
   (Contributed by Eric Snow in :gh:`124548`.)
-* The default ``ProcessPoolExecutor`` start method (see
-  :ref:`multiprocessing-start-methods`) changed from *fork* to *forkserver* on
-  platforms other than macOS & Windows. If you require the threading
-  incompatible *fork* start method you must explicitly request it by
-  supplying a *mp_context* to :class:`concurrent.futures.ProcessPoolExecutor`.
-  (Contributed by Gregory P.  Smith in :gh:`84559`.)
+
+.. _whatsnew314-concurrent-futures-start-method:
+
+* The default :class:`~concurrent.futures.ProcessPoolExecutor`
+  :ref:`start method <multiprocessing-start-methods>` changed
+  from :ref:`fork <multiprocessing-start-method-fork>` to :ref:`forkserver
+  <multiprocessing-start-method-forkserver>` on platforms other than macOS and
+  Windows where it was already :ref:`spawn <multiprocessing-start-method-spawn>`.
+
+  If the threading incompatible *fork* method is required, you must explicitly
+  request it by supplying a multiprocessing context *mp_context* to
+  :class:`~concurrent.futures.ProcessPoolExecutor`.
+
+  See :ref:`forkserver restrictions <multiprocessing-programming-forkserver>`
+  for information and differences with the *fork* method and how this change
+  may affect existing code with mutable global shared variables and/or shared
+  objects that can not be automatically :mod:`pickled <pickle>`.
+
+  (Contributed by Gregory P. Smith in :gh:`84559`.)
+
 
 contextvars
 -----------
@@ -637,18 +667,30 @@ mimetypes
 multiprocessing
 ---------------
 
-* The default start method (see :ref:`multiprocessing-start-methods`) changed
-  from *fork* to *forkserver* on platforms other than macOS & Windows where
-  it was already *spawn*. If you require the threading incompatible *fork*
-  start method you must explicitly request it using a context from
-  :func:`multiprocessing.get_context` (preferred) or change the default via
-  :func:`multiprocessing.set_start_method`.
+.. _whatsnew314-multiprocessing-start-method:
+
+* The default :ref:`start method <multiprocessing-start-methods>` changed
+  from :ref:`fork <multiprocessing-start-method-fork>` to :ref:`forkserver
+  <multiprocessing-start-method-forkserver>` on platforms other than macOS and
+  Windows where it was already :ref:`spawn <multiprocessing-start-method-spawn>`.
+
+  If the threading incompatible *fork* method is required, you must explicitly
+  request it via a context from :func:`multiprocessing.get_context` (preferred)
+  or change the default via :func:`multiprocessing.set_start_method`.
+
+  See :ref:`forkserver restrictions <multiprocessing-programming-forkserver>`
+  for information and differences with the *fork* method and how this change
+  may affect existing code with mutable global shared variables and/or shared
+  objects that can not be automatically :mod:`pickled <pickle>`.
+
   (Contributed by Gregory P. Smith in :gh:`84559`.)
+
 * :mod:`multiprocessing`'s ``"forkserver"`` start method now authenticates
   its control socket to avoid solely relying on filesystem permissions
   to restrict what other processes could cause the forkserver to spawn workers
   and run code.
   (Contributed by Gregory P. Smith for :gh:`97514`.)
+
 * The :ref:`multiprocessing proxy objects <multiprocessing-proxy_objects>`
   for *list* and *dict* types gain previously overlooked missing methods: